diff --git a/quorum-key-management/src/SUMMARY.md b/quorum-key-management/src/SUMMARY.md index 4f51de3..393a710 100644 --- a/quorum-key-management/src/SUMMARY.md +++ b/quorum-key-management/src/SUMMARY.md @@ -30,6 +30,7 @@ * [Transaction Approval](generated-documents/level-2/fixed-location/approver/approve-transaction.md) * [Operator](generated-documents/level-2/fixed-location/operator/index.md) * [PGP Key Provisioning](generated-documents/level-2/fixed-location/operator/pgp-key-provisioning.md) + * [Ceremony SD Card Provisioning](generated-documents/level-2/fixed-location/operator/ceremony-sd-card-provisioning.md) * [Namespace Entropy Ceremony](generated-documents/level-2/fixed-location/operator/namespace-entropy-ceremony.md) * [Quorum Entropy Ceremony](generated-documents/level-2/fixed-location/operator/quorum-entropy-ceremony.md) * [PYTH-SLN - Sign Transaction](generated-documents/level-2/fixed-location/operator/coins/pyth-spl/sign-transaction.md) \ No newline at end of file diff --git a/quorum-key-management/src/component-documents/ceremony-repository.md b/quorum-key-management/src/component-documents/ceremony-repository.md index 92c767a..deea475 100644 --- a/quorum-key-management/src/component-documents/ceremony-repository.md +++ b/quorum-key-management/src/component-documents/ceremony-repository.md @@ -8,13 +8,13 @@ This repository holds data pertaining to ceremonies. The primary data consists o * Transaction approvals -* Tamper proofing evidence +* Trusted PGP keyring + +* Shardfile * Policies (such as spending rules) -* Trusted PGP keys - -* Participants +* Ceremony logs ## Directives @@ -31,16 +31,15 @@ ceremonies/ / log.txt - [ ] TODO: write a layout for the log - tamper_evidence/ - .jpeg - .jpeg - transactions/ - .tx.json + workflow_payloads/ + workflow_payload_.json + workflow_payload_.json.sig +blockchain_metadata/ + sol_nonce_address.txt policies/ spending-policy.json [NOT IMPLEMENTED] -keychain/ - / - .asc +keyring.asc +shardfile.asc ``` ## Procedure: Setting up Repository @@ -61,177 +60,6 @@ keychain/ 1. The PR should be merged using a signed commit via the git CLI -## Procedure: Adding Scripts - -### Script: Verify OpenPGP Certificate Signatures (`verify-openpgp-certificates.sh`) - -This script is used during ceremonies where operators want to ensure that a set of OpenPGP certificates are signed by each of the operators at least once. The way it is used is: - -1. Plugs in the Ceremony SD card - -1. The operator plugs in their smart card which holds their OpenPGP subkeys - -1. Runs the `verify-openpgp-certificates.sh` - -#### Provisioning - -1. Create a file called `verify-openpgp-certificates.sh` in the `scripts/` directory - -1. Add the following contents to the file: -- [ ] TODO, modify to check signatures on the pub key -- [ ] TODO review script - ``` - #!/bin/bash - - set -eu -o pipefail - - DIRECTORY="$1" - - if ! compgen -G "$DIRECTORY/*.asc" > /dev/null; then - echo "No .asc files found in the directory." - exit 1 - fi - - if ! gpg --card-status > /dev/null 2>&1; then - echo "No smart card detected. Please insert a smart card." - exit 1 - fi - - smart_card_id=$(gpg --card-status | grep sec | cut -d'/' -f2 | cut -d' ' -f1) - - for asc_file in "$DIRECTORY"/*.asc; do - gpg --import "$asc_file" - done - - for asc_file in "$DIRECTORY"/*.asc; do - sig_exists="false" - - for sig_file in "$DIRECTORY"/*.asc.sig; do - sigfile_basename=$(basename "$sig_file" .asc.sig) - ascfile_basename=$(basename "$asc_file" .asc) - - if [[ "$sigfile_basename" != "$ascfile_basename" ]]; then - continue - fi - - sig_key_id=$(gpg --verify "$sig_file" 2>&1 | grep 'Primary key fingerprint' | cut -d' ' -f4- | tr -d ' ') - trimmed_key_id="${sig_key_id: -16}" - - if [[ "$trimmed_key_id" == "$smart_card_id" ]]; then - sig_exists="true" - break - fi - done - - if [[ "$sig_exists" == "false" ]]; then - printf "\nWARNING: Signature for %s by operator key %s does not exist\n" "$asc_file" "$smart_card_id" - fi - done - - ``` - -### Script: Verify Workflow Payload Has Valid OpenPGP Signatures (`verify-workload-payloads.sh`) - -This script is used during ceremonies to ensure that the payload data from the "Proposer" and "Approvers" have been signed by trusted keys from the `keychain/` directory. The script `verify-openpgp-signatures.sh` is used to load and verify the validity of keys before this script can be used. - -1. Run the `verify-openpgp-certificates` scripts - -1. Plug in the "Workflow" SD card and run the `verify-workload-payload.sh` - -#### Provisioning - -1. Create a file called `verify-workload-payload.sh` in the `scripts/` directory - -1. Add the following content to the file: -- [ ] TODO: review script - ``` - #!/bin/bash - - DIRECTORY=$1 - - declare -a key_ids - - while IFS= read -r line; do - key_id=$(echo "$line" | awk -F: '/^pub/{print $5}') - if [[ -n "$key_id" ]]; then - key_ids+=("$key_id") - fi - done < <(gpg --list-keys --with-colons) - - check_key_id() { - local search_key_id="$1" - for id in "${key_ids[@]}"; do - if [[ "$id" == "$search_key_id" ]]; then - return 0 - fi - done - return 1 - } - - for tx in "$DIRECTORY"/*.json; do - basename=$(basename "$tx" .json) - number_of_sigs=0 - tx_sig="$DIRECTORY/$basename.json.sig" - - if [[ ! -f "$tx_sig" ]]; then - echo "WARNING: No signature file found for transaction $tx." - continue - fi - - sig_key_id=$(gpg --verify "$tx_sig" 2>&1 | grep 'Primary key fingerprint' | cut -d' ' -f4- | tr -d ' ') - trimmed_key_id="${sig_key_id: -16}" - - if check_key_id "$trimmed_key_id"; then - ((number_of_sigs++)) - else - echo "Key ID $trimmed_key_id not found in key_ids array." - fi - - if (( number_of_sigs < 2 )); then - echo "WARNING: Insufficient signatures ($number_of_sigs) for transaction $tx." - fi - done - ``` - -## Procedure: Provision Ceremony 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 Ceremony SD Card once provisioned will be used in creating the [tamper proofed airgap bundle](#air-gapped-bundle) - -// ANCHOR: provision-ceremony-sd-card -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. Find the SD card block device name using `lsblk` - -1. Create a directory for OpenPGP public certificates on the SD card: `mkdir dev//public_certificates` - -1. Copy the `.asc` and `.sig` signature files from `keychain` directory in the Ceremonies repository to into the `public_certificates` dir on the SD card - -1. Create a directory for scripts on the SD card: `mkdir dev//scripts` - -1. Copy the contents of the scripts directory from the Ceremonies repository into the `scripts/` directory on the SD card - -1. Use the `sdtool` to lock the card - -{{ #include ../sdtool-instructions.md:steps }} - -1. Label the card "Ceremony [date]" - -### Tamper Proofing - -{{ #include ./tamper-evidence-methods.md:vsbwf-procedure-sealing }} - -// ANCHOR_END: provision-ceremony-sd-card - // ANCHOR_END: content /* ANCHOR_END: all */ diff --git a/quorum-key-management/src/component-documents/inventory-repository.md b/quorum-key-management/src/component-documents/inventory-repository.md new file mode 100644 index 0000000..bac5c41 --- /dev/null +++ b/quorum-key-management/src/component-documents/inventory-repository.md @@ -0,0 +1,19 @@ +# Inventory Repository + +This repository is used to keep track of available inventory and tamper proofing evidence + +## Repository Structure + +``` +computers/ + / + description.txt + tamper_evidence_front.jpeg + tamper_evidence_back.jpeg +bundles/ + / + description.txt + tamper_evidence_front.jpeg + tamper_evidence_back.jpeg +``` + diff --git a/quorum-key-management/src/generated-documents/level-2/fixed-location/operator/ceremony-sd-card-provisioning.md b/quorum-key-management/src/generated-documents/level-2/fixed-location/operator/ceremony-sd-card-provisioning.md new file mode 100644 index 0000000..7ba81c3 --- /dev/null +++ b/quorum-key-management/src/generated-documents/level-2/fixed-location/operator/ceremony-sd-card-provisioning.md @@ -0,0 +1,29 @@ +# Ceremony SD Card Provisioning + +## Requirements + +* [SD Card Booster Pack](../provisioner/provision-sd-card.md) + +* [Personal PGP Keys](/key-types.html#personal-pgp-keypair) + +* Online computer + +## Procedure + +1. Turn on the computer + +1. Open the SD Card Booster Pack + +1. Plug in a fresh SD card into computer + +1. Navigate to the ceremony repository for the ceremony being executed + +1. Create a directory called `workflow-inputs` on the SD card + +1. Copy all transaction workflow payloads from the appropriate dated directory found in `ceremonies/workflow-payloads/` into the `workflow-payloads/` directory on the SD card + +1. Copy the `shardfile.asc` from the ceremony repository onto the SD card + +1. Copy the `keyring.asc` from the ceremony repository onto the SD card + +1. Copy any other `blockchain_metadata/` as required, for example `nonce_address.txt` for SOL transactions \ No newline at end of file diff --git a/quorum-key-management/src/generated-documents/level-2/fixed-location/operator/coins/pyth-spl/sign-transaction.md b/quorum-key-management/src/generated-documents/level-2/fixed-location/operator/coins/pyth-spl/sign-transaction.md index 024dda6..70f2285 100644 --- a/quorum-key-management/src/generated-documents/level-2/fixed-location/operator/coins/pyth-spl/sign-transaction.md +++ b/quorum-key-management/src/generated-documents/level-2/fixed-location/operator/coins/pyth-spl/sign-transaction.md @@ -10,21 +10,17 @@ {{ #include ../../../../operator-requirements.md:requirements }} -* Ceremony SD card - -* Transaction SD card (with workflow payloads) +* [Ceremony SD card](../../ceremony-sd-card-provisioning.md) ## Procedure -1. Verify all transactions for the ceremony in the `ceremonies` repository, ensuring that all the transactions are properly signed by the proposer and the approver using PGP keys which have been checked into ceremonies repository. - -1. Copy the transactions and signatures to an SD card - 1. Enter the designated location with the quorum of operators and all required equipment 1. Lock access to the location - there should be no inflow or outflow of people during the ceremony -1. Retrieve sealed Air-Gapped bundle and polaroid from locked storage +1. Place Ceremony SD card in High Visibility Storage + +1. Retrieve sealed Air-Gapped bundle, polaroid of tamper evidence, and online laptop from locked storage ### Unsealing Tamper Proofing @@ -34,70 +30,62 @@ ### Ceremony +#### Prepare Transaction: Online Machine 1. Turn on online machine -1. Once booted, run `icepick workflow sol broadcast --nonce-address=` command +1. Retrieve the Ceremony SD card from High Visibility Storage and plug it into the computer - - [ ] TODO find a place for the nonce_address in the ceremony repo or airgapOS +1. Run the command: `icepick workflow sol broadcast --nonce-address=` - * Plug in "Transaction" SD card + * The nonce address is found on the Ceremony SD card - * Await completion message before removing "Transaction" SD card + * Await completion message before removing Ceremony SD card and placing it back - * 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 + * 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 after the workflow payloads are signed on the offline machine -1. Plug in SD card labelled "AirgapOS" into the air-gapped machine +#### Sign Transaction: Air-Gapped Machine +1. Retrieve AirgapOS SD card and plug it into the air-gapped machine 1. Boot the computer -1. Unplug the "AirgapOS" SD card and place it in High Visibility Storage +1. Unplug the AirgapOS SD card and place it in High Visibility Storage -1. Plug in SD card labelled "Keychain" +1. Retrieve Ceremony SD card from High Visibility Storage and plug it into the air-gapped machine -1. Use detached signatures of the keys on the SD cards to verify the pub certs. Each operator should verify that the each key in the Keychain has been signed by that operator's key. - - 1. Plug in a smart card with Quorum PGP Key - - 1. Run the `verify-openpgp-certifiates.sh` script +1. TODO: command to verify keyring data from Ceremony SD card and load it into local keychain 1. Repeat for all operators, using their respective smart cards +1. TODO run command that verifies all workflow data + 1. Ensure that the script doesn't output any "WARNING" messages to the console. If it does, abort the ceremony and initiate incident response. -1. Unplug the "Keychain" SD card and place it in High Visibility Storage - -1. Insert SD card labelled "Shardfile" - 1. If no prompt appears, run the command: * `keyfork recover shard --daemon` 1. Follow on screen prompts -1. Unplug SD card labelled "Shardfile" and place it in High Visibility Storage - -1. Retrieve the "Transaction" SD card from High Visibility Storage and plug in the "Transaction" SD card - -1. For each transaction, verify that the signature is made by trusted keys that are loaded in the gpg keyring: - - * Run the `verify-workload-payload.sh` script - 1. Run the `icepick` command with the transaction payload * `icepick workflow sol transfer-token --input-file=` * Follow on screen prompts -1. Unplug the "Transaction" SD card and place it in High Visibility Storage +1. Unplug the Ceremony SD card and place it in High Visibility Storage -### Broadcast Transaction +#### Broadcast Transaction: Online Machine -1. Plug the "Transaction" SD card into online machine +1. Retrieve Ceremony SD from High Visibility Storage and plug it into online machine 1. The still running broadcast command on the online machine will broadcast the transaction automatically 1. The url that's found in the response after a successful broadcast should be reviewed and committed to the ceremony repository +#### Repeat + +1. You may repeat previous steps as many times as necessary to process all workflow payloads + ### Finalization 1. Shut down online machine @@ -112,9 +100,5 @@ * AirgapOS SD card - * Shardfile SD card - - * Ceremony SD card - {{ #include ../../../../../../component-documents/tamper-evidence-methods.md:vsbwf-procedure-sealing}} diff --git a/quorum-key-management/src/generated-documents/level-2/fixed-location/operator/namespace-entropy-ceremony.md b/quorum-key-management/src/generated-documents/level-2/fixed-location/operator/namespace-entropy-ceremony.md index 8c21866..fdc7019 100644 --- a/quorum-key-management/src/generated-documents/level-2/fixed-location/operator/namespace-entropy-ceremony.md +++ b/quorum-key-management/src/generated-documents/level-2/fixed-location/operator/namespace-entropy-ceremony.md @@ -4,7 +4,7 @@ This is a ceremony for generating and sharding entropy to a set of existing Quor ## Requirements -* [Quorum PGP key pairs](/key-types.md#quorum-pgp-keypair) +* 2 or more Operators {{ #include ../../operator-requirements.md:requirements }} @@ -16,11 +16,11 @@ This is a ceremony for generating and sharding entropy to a set of existing Quor ## Procedure -1. Enter the designated location with the 2 operators and all required equipment +1. Enter the designated location with the operators and all required equipment 1. Lock access to the location - there should be no inflow or outflow of people during the ceremony -1. Retrieve Air-Gapped Bundle from locked storage +1. Retrieve Air-Gapped Bundle and polaroid tamper evidence from locked storage ### Unsealing Tamper Proofing @@ -40,9 +40,9 @@ This is a ceremony for generating and sharding entropy to a set of existing Quor 1. Run the command to generate new entropy and shard it to quorum of public certificates of the input shardfile: - * `keyfork mnemonic generate --size 256 --shard-to ,` + * `keyfork mnemonic generate --size 256 --shard-to ,` - * NOT IMPLEMENTED YET + * TODO: NOT IMPLEMENTED YET 1. Back up the `` to any desired number of SD cards, and label each "Shardfile [unique_id] [date]" @@ -50,8 +50,6 @@ This is a ceremony for generating and sharding entropy to a set of existing Quor * `keyfork recover shard --daemon` -1. If an OpenPGP certificate was derived, store the public key on a SD card, separate from the shardfiles - ### Finalizing Ceremony 1. Gather all the original items that were in the air-gapped bundle: @@ -60,8 +58,4 @@ This is a ceremony for generating and sharding entropy to a set of existing Quor * AirgapOS SD card - * Shardfile SD card - - * Ceremony SD card - {{ #include ../../../../component-documents/tamper-evidence-methods.md:vsbwf-procedure-sealing}} \ No newline at end of file diff --git a/quorum-key-management/src/generated-documents/level-2/fixed-location/operator/pgp-key-provisioning.md b/quorum-key-management/src/generated-documents/level-2/fixed-location/operator/pgp-key-provisioning.md index 830d769..b52ea6e 100644 --- a/quorum-key-management/src/generated-documents/level-2/fixed-location/operator/pgp-key-provisioning.md +++ b/quorum-key-management/src/generated-documents/level-2/fixed-location/operator/pgp-key-provisioning.md @@ -38,10 +38,6 @@ * AirgapOS SD card - * Shardfile SD card - - * Ceremony SD card - {{ #include ../../../../component-documents/tamper-evidence-methods.md:vsbwf-procedure-sealing}} diff --git a/quorum-key-management/src/generated-documents/level-2/fixed-location/operator/quorum-entropy-ceremony.md b/quorum-key-management/src/generated-documents/level-2/fixed-location/operator/quorum-entropy-ceremony.md index a4a4bdf..681c6e7 100644 --- a/quorum-key-management/src/generated-documents/level-2/fixed-location/operator/quorum-entropy-ceremony.md +++ b/quorum-key-management/src/generated-documents/level-2/fixed-location/operator/quorum-entropy-ceremony.md @@ -1,6 +1,6 @@ # Quorum Entropy Ceremony -This is a ceremony for generating entropy which is used to derive Quorum PGP keys, load them into smart cards and shard entropy to them. Optionally a disaster recovery PGP key can be derived. +This is a ceremony for generating entropy which is used to derive Quorum PGP keys, load them into smart cards and shard entropy to them. ## Requirements @@ -8,7 +8,7 @@ This is a ceremony for generating entropy which is used to derive Quorum PGP key * [SD Card Booster Pack](../provisioner/provision-sd-card.md) -* `N` SD cards in the chosen `M of N` quorum +* `N` Smart Cards in the chosen `M of N` quorum * [Shardfile SD Card](../provisioner/copy-shardfile-sd-card.md) @@ -16,11 +16,11 @@ This is a ceremony for generating entropy which is used to derive Quorum PGP key ## Procedure -1. Enter the designated location with at least 2 operators and all required equipment +1. Enter the designated location with required personnel and equipment 1. Lock access to the location - there should be no inflow or outflow of people during the ceremony -1. Retrieve Air-Gapped Bundle from locked storage +1. Retrieve Air-Gapped Bundle and polaroid tamper evidence from locked storage ### Unsealing Tamper Proofing @@ -40,7 +40,7 @@ This is a ceremony for generating entropy which is used to derive Quorum PGP key 1. Run the keyfork wizard to generate entropy, derive OpenPGP certs, load them into smart cards, and shard the secret to the generated OpenPGP keys - * `keyfork wizard generate-shard-secret --threshold --max --keys-per-shard=2 --output shardfile.asc --cert-output keyring.asc` + * `keyfork wizard generate-shard-secret --threshold --max --keys-per-shard= --output shardfile.asc --cert-output keyring.asc` * NOT IMPLEMENTED YET @@ -58,8 +58,6 @@ This is a ceremony for generating entropy which is used to derive Quorum PGP key * `keyfork recover shard --daemon` - 1. If an OpenPGP certificate was derived, store the public key on a SD card, separate from the shardfiles - 1. Unplug the SD card and place it in High Visibility Storage 1. Label the SD card "Shardfile [date]" @@ -73,8 +71,4 @@ This is a ceremony for generating entropy which is used to derive Quorum PGP key * AirgapOS SD card - * Shardfile SD card - - * Ceremony SD card - {{ #include ../../../../component-documents/tamper-evidence-methods.md:vsbwf-procedure-sealing}} \ No newline at end of file diff --git a/quorum-key-management/src/generated-documents/level-2/operator-requirements.md b/quorum-key-management/src/generated-documents/level-2/operator-requirements.md index 555976a..9f70dbc 100644 --- a/quorum-key-management/src/generated-documents/level-2/operator-requirements.md +++ b/quorum-key-management/src/generated-documents/level-2/operator-requirements.md @@ -6,7 +6,7 @@ * [Personal PGP key pairs](/key-types.md#personal-pgp-keypair) -* Air-gapped bundle +* [Air-gapped bundle](/generated-documents/level-2/fixed-location/provisioner/air-gapped-bundle.md) * Adequate quorum of operators (M individuals of a M of N quorum)