public
/
docs
5
0
Fork 0
Code Issues 14 Pull Requests 1 Packages Projects Releases Wiki Activity

qvs: fix TODOs, fix invalid commands or TODO commands

This commit is contained in:
Ryan Heywood 2025-01-28 19:15:06 -05:00
parent ec9d74214b
commit 695421bdbe
Signed by: ryan
GPG Key ID: 8E401478A3FBEF72
9 changed files with 160 additions and 159 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
quorum-vault-system/src/SUMMARY.md
View File

@ -14,8 +14,8 @@
* [Fixed-Location]()
* [Procurer](generated-documents/level-2/fixed-location/procurer/index.md)
* [Procure Facility](generated-documents/level-2/fixed-location/procurer/procure-facility.md)
* [Procure SD Card Pack](generated-documents/level-2/fixed-location/procurer/procure-sd-card-pack.md)
* [Procure Tamper Proofing Equipment](generated-documents/level-2/fixed-location/procurer/procure-tamper-proofing-equipment.md)
* [Procure SD Card Pack](generated-documents/level-2/fixed-location/procurer/procure-sd-card-pack.md)
* [Procure Hardware](generated-documents/level-2/fixed-location/procurer/procure-hardware.md)
* [Provisioner](generated-documents/level-2/fixed-location/provisioner/index.md)
* [Provision Ceremony Repository](generated-documents/level-2/fixed-location/provisioner/provision-ceremonies-repository.md)
@ -30,4 +30,4 @@
* [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)
* [PYTH-SLN - Sign Transaction](generated-documents/level-2/fixed-location/operator/coins/pyth-spl/sign-transaction.md)
* [SOL - Transfer Token](generated-documents/level-2/fixed-location/operator/coins/sol/transfer-token.md)

18
quorum-vault-system/src/component-documents/ceremony-repository.md
View File

@ -59,19 +59,31 @@ keys/
* `git pull origin main`
1. If using a certificate from [Personal PGP Key Provisioning](/generated-documents/all-levels/pgp-key-provisioning.html):
1. Obtain the fingerprint for the certificate:
* `fingerprint="$(sq keyring cert.asc | awk '{ print $2 }')"`
2. Copy the certificate to a name based on the keyring:
* `cp cert.asc "${fingerprint}.asc"`
1. If exporting a certificate from GnuPG:
1. Find your key fingerprint:
`gpg --list-keys`
* `gpg --list-keys`
1. Export your OpenPGP public certificate:
* `gpg --export --armor <key_fingerprint> > <key_fingerprint>.asc
* `gpg --export --armor <key_fingerprint> > <key_fingerprint>.asc`
1. Place the file in `keys/all/<key_fingerprint>.asc`
1. Create signed git commit:
* `git commit -m "add <name> pgp key"`
* `git commit -S -m "add <name> pgp key"`
1. Push to the commit:

97
quorum-vault-system/src/component-documents/openpgp-setup.md
View File

@ -1,104 +1,41 @@
/* 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.
Setting up a personal PGP key pair is necessary for a number of different
aspects while bootstrapping QVS. The keys are a fundamental building block, and
as such need to be set up in a manner that minimizes exposure risks.
## Generating Keys using `keyfork` and `openpgp-card-tools`
## Generating Keys using `keyfork` and `oct`
// ANCHOR: steps-keyfork
1. Generate a mnemonic:
* `keyfork mnemonic generate --size 256 > mnemonic.txt`
1. Insert a smartcard into the system, and get its ID:
1. Setting socket may not be necessary anymore (TODO test on Airgap):
* `identifier="$(oct list -i | head -1)`
* `export KEYFORKD_SOCKET_PATH=/tmp/keyforkd.socket`
1. Generate a mnemonic, encrypting to a newly-generated key:
1. Recover mnemonic to `keyforkd` and send process to background
* `keyfork mnemonic generate --size 256 --encrypt-to-self cert.asc,output=encrypted-mnemonic.asc --provision openpgp-card,identifier="$identifier"`
* `keyfork recover mnemonic < mnemonic.txt`
1. If additional keys are required, recover the Keyfork key from the encrypted
mnemonic:
* ctrl + z
* `gpg --import cert.asc`
* `bg`
* `gpg --decrypt encrypted-mnemonic.asc | KEYFORK_PROMPT_TYPE=headless keyfork recover mnemonic &`
1. Set expiration using the `KEYFORK_OPENPGP_EXPIRE` environment variable:
* Remove your previous key, and plug in the new key.
* `export KEYFORK_OPENPGP_EXPIRE=2y`
* `identifier="$(oct list -i | head -1)"`
1. Derive PGP keypair:
* `keyfork provision openpgp-card --identifier "$identifier" --account-id 0`
* `keyfork derive openpgp "full_name (alias) <email>" > priv.asc`
* e.g `keyfork derive openpgp "Ryan Heywood (RyanSquared) <ryan@distrust.co>" > priv.asc`
1. Provision at least two smart cards for redundancy:
* Get the `smart_card_id`:
* `oct list`
* Seed the smart card with the private OpenPGP key:
* `oct admin --card <smart_card_id> import priv.asc`
* Set the admin and user PINs for the card
* You can come up with your own alpha numeric PIN or use the following command to generate the two PINs (they should be different):
* `keyfork mnemonic generate --size 256 | awk '{ print $1, $2, $3, $4, $5, $6 }' > smart-card-pin.txt`
* `oct pin --card <smart_card_id> set-user`
* Enter the `<user_smart_card_pin>`
* `oct pin --card <smart_card_id> set-admin`
* Enter the `<admin_smart_card_pin>`
1. Import PGP key into keyring
* `gpg --import priv.asc`
1. Use the `gpg --list-keys` command to list GPG keys in the local keychain. Identify your key and take note of the key ID.
* Example printout of the command, where `F4BF5C81EC78A5DD341C91EEDC4B7D1F52E0BA4D` is the key ID.
```
/home/user/.gnupg/pubring.kbx
-----------------------------
pub rsa4096 2022-03-26 [C] [expires: 2026-03-27]
F4BF5C81EC78A5DD341C91EEDC4B7D1F52E0BA4D
uid [ unknown] Anton Livaja <anton@livaja.me>
uid [ unknown] Anton Livaja (Work) <anton@distrust.co>
sub rsa4096 2022-03-26 [S] [expires: 2026-03-27]
sub rsa4096 2022-03-26 [E] [expires: 2026-03-27]
sub rsa4096 2022-03-26 [A] [expires: 2026-03-27]
```
1. Rename the private key file to contain the `key_id`:
* `mv priv.asc <key_id>.priv`
1. Export the public key:
* `gpg --export --armor <key_id> > <key_id>.pub`
1. Bundle all data and encrypt it
* `mkdir backup_bundle/`
* `mv <key_id>.pub <key_id>.priv smart-card-pin.txt backup_bundle/`
* `tar -cvf backup_bundle.tar backup_bundle/`
* `gpg --armor -er <key_id> backup_bundle.tar`
1. Copy the encrypted bundle, `backup_bundle.tar.gpg` to an SD card. Repeat the process as many times as desired. Minimum of 3 SD Card backups is recommended.
1. Insert an SD card to contain the public certificate and the encrypted mnemonic.
* `lsblk`
* `sudo mount /dev/<your_device> media/`
* `cp backup_bundle.tar.gpg /media`
* `cp cert.asc encrypted-mnemonic.asc /media`
// ANCHOR_END: steps-keyfork

24
quorum-vault-system/src/generated-documents/level-2/fixed-location/approver/approve-transaction.md
View File

@ -48,16 +48,32 @@ The approver is responsible for verifying a transaction proposed by a [proposer]
1. Copy the git repo locally from the Ceremony SD card
1. Verify the PGP key of the Proposer is valid
* `cp -r /media/external/ceremonies /root/ceremonies; cd /root/ceremonies`
1. Verify the detached sig for the payload
1. Verify the detached signature for the payload
1. To sign the transaction payload and produce a detached signature use:
* `gpg --verify <filename> <filename>.1.sig`
* `gpg --detach-sig <filename>`
* The filename will be of format: `keys/ceremonies/<date>/payloads/payload_<number>.json`
1. Verify the key is authenticated:
* `sq-wot --gpg list "<their@email.co>"`
* Ensure the output of the command includes "fully authenticated"
1. Sign the transaction payload:
* `gpg --detach-sign <filename> > <filename>.2.sig`
1. Create a signed git commit:
* `git commit -S -m "add <name> pgp key"`
1. Copy the updated ceremonies repo to the SD card
* `cp -r . /media/external/ceremonies`
1. Unplug the SD card from the air-gapped machine
1. Plug in the SD card into the online machine

51
quorum-vault-system/src/generated-documents/level-2/fixed-location/operator/coins/pyth-spl/sign-transaction.md → quorum-vault-system/src/generated-documents/level-2/fixed-location/operator/coins/sol/transfer-token.md
View File

@ -26,6 +26,8 @@
1. Place all contents except for the laptop into High Visibility Storage
### Online Machine: Acquire Nonce
1. Turn on online machine
1. Retrieve the Ceremony SD card from High Visibility Storage and plug it into the computer
@ -34,10 +36,12 @@
* The nonce address is found on the Ceremony SD card
* Await completion message before removing Ceremony SD card and placing it back
* Await completion message before removing Ceremony 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 after the workflow payloads are signed on the offline machine
### Offline Machine: Create and Sign Transaction
1. Retrieve AirgapOS SD card and plug it into the air-gapped machine
1. Boot the computer
@ -46,29 +50,47 @@
1. Retrieve Ceremony SD card from High Visibility Storage and plug it into the air-gapped machine
1. TODO: command to verify keyring data from Ceremony SD card and load it into local keychain
1. Verify keyring data from the Ceremony SD card:
1. Repeat for all operators, using their respective smart cards
1. Import keys into the system
1. TODO run command that verifies all workflow data
* `gpg --import keys/all/*.asc`
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. Plug in the operator's smartcard, and ensure it is loaded:
1. If no prompt appears, run the command:
* `gpg --card-status`
* `keyfork recover shard --daemon`
1. Print the list of trusted keys:
* `sq-wot --gpg list`
1. Repeat for every operator, ensuring all keys are cross-trusted.
1. Terminate `gpg-agent`: `killall gpg-agent`
1. Verify all signatures for the workflow data:
* `for file in <payload.json>.*.sig; do echo "Verifying: $file"; gpg --verify "${file}.json" "$file"; done`
* Ensure that the script doesn't output any "WARNING" messages to the console. If it does, abort the ceremony and initiate incident response.
1. Start Keyfork using the relevant Shardfile:
* `keyfork recover shard --daemon /media/external/shard.asc`
* The Shardfile may be named something else. Use `find /media/external -type f -name '*shard*.asc'` to list all files.
1. Follow on screen prompts
1. Unplug the Shard SD card and place it in High Visibility Storage
1. Run the `icepick` command with the transaction payload
* `icepick workflow sol transfer-token --input-file=<payload.json>`
* `icepick workflow sol transfer-token --input-file=<(jq .values <payload.json>)`
* Follow on screen prompts
1. Unplug the Ceremony SD card and place it in High Visibility Storage
#### Broadcast Transaction: Online Machine
### Broadcast Transaction: Online Machine
1. Retrieve Ceremony SD from High Visibility Storage and plug it into online machine
@ -76,17 +98,17 @@
1. The url that's found in the response after a successful broadcast should be reviewed and committed to the ceremony repository
#### Repeat
### Repeat
1. You may repeat previous steps as many times as necessary to process all workflow payloads
### Finalization
## Finalization
1. Shut down online machine
1. Shut down the air gapped machine
#### Sealing
### Sealing
1. Gather all the original items that were in the air-gapped bundle:
@ -95,4 +117,3 @@
* AirgapOS SD card
{{ #include ../../../../../../component-documents/tamper-evidence-methods.md:vsbwf-procedure-sealing}}

6
quorum-vault-system/src/generated-documents/level-2/fixed-location/operator/namespace-entropy-ceremony.md
View File

@ -32,9 +32,7 @@ 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 <path_to_input_shard>,<output_shard_name>`
* TODO: NOT IMPLEMENTED YET
* `keyfork mnemonic generate --size 256 --shard-to <path_to_input_shard>,output=<output_shard_name>`
1. Unseal an SD card pack
@ -52,7 +50,7 @@ This is a ceremony for generating and sharding entropy to a set of existing Quor
1. Optionally write an `autorun.sh` file to the Shardfile SD card containing the following command:
* `keyfork recover shard --daemon`
* `keyfork recover shard --daemon /media/external/<shard_file_name>`
1. Gather all the original items that were in the air-gapped bundle:

6
quorum-vault-system/src/generated-documents/level-2/fixed-location/operator/quorum-entropy-ceremony.md
View File

@ -30,11 +30,9 @@ This is a ceremony for generating entropy which is used to derive Quorum PGP key
1. Once booted, remove the AirgapOS SD card and place it into High Visibility Storage
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
1. Run the relevant keyfork wizard to perform the ceremony:
* `keyfork wizard generate-shard-secret --threshold <M> --max <N> --keys-per-shard=<num_of_smart_cards_to_provision> --output shardfile.asc --cert-output keyring.asc`
* NOT IMPLEMENTED YET
* `keyfork wizard generate-shard-secret --threshold <M> --max <N> --keys-per-shard=<number_of_smart_cards_per_operator> --output shardfile.asc --cert-output keyring.asc`
1. Unseal an SD card pack

63
quorum-vault-system/src/generated-documents/level-2/fixed-location/proposer/create-transaction-payload.md
View File

@ -2,19 +2,24 @@
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:
The proposer MUST include the workflow type and all arguments required by a workflow, such as `from_address`, `to_address`, `asset_name`, etc., as well as a UTC datetime representing the time when the transaction is proposed.
* Token Name (SOL, PYTH-SPL, ETH, ETH-PYTH, BTC etc.)
The proposer must combine these values into a JSON file, such as:
* FROM address
```json
{
"workflow": ["cosmos", "withdraw"],
"values": {
"delegate_address": "kyve1q9w3nar74up6mxnwd428wpr5nffcw3360tkxer",
"validator_address": "kyvevaloper1ghpmzfuggm7vcruyhfzrczl4aczy8gas8guslh",
"asset_name": "KYVE",
"asset_amount": "0.4",
"chain_name": "korellia"
},
"proposal_datetime": "2025-01-28T18:18:00"
}
```
* 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
@ -60,39 +65,53 @@ The proposer must combine these values into a single message, which can be a sim
1. Copy the git repo locally from the Ceremony SD card
1. Define a new file `payload_<num>.json`, for example `payload_1.json`
* `cp -r /media/external/ceremonies /root/ceremonies; cd /root/ceremonies`
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/`
* `mkdir -p keys/ceremonies/2024-01-01/payloads`
1. Determine a new filename `payload_<num>.json`, for example `payload_1.json`
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>"
"workflow": ["<workflow_namespace>", "<workflow_name>"],
"values": {
"<workflow_field>": "<workflow_value>"
},
"proposal_datetime": "<datetime>"
}
```
Example data object:
```json
{
"token-name": "PYTH-SLN",
"token-amount": "42",
"from_address": "2Z72E62atYfpatQeqPvHZMaabmuz664xq5MRWv9xM5NX",
"to_address": "BNQr6T2UAuEPux1fuiygM6chrT5GkHKaMWeTTaRLmR7g",
"datetime": "<date:time>"
"workflow": ["cosmos", "withdraw"],
"values": {
"delegate_address": "kyve1q9w3nar74up6mxnwd428wpr5nffcw3360tkxer",
"validator_address": "kyvevaloper1ghpmzfuggm7vcruyhfzrczl4aczy8gas8guslh",
"asset_name": "KYVE",
"asset_amount": "0.4",
"chain_name": "korellia"
},
"proposal_datetime": "2025-01-28T18:18:00"
}
```
1. Sign the data in the CLI using `gpg` or another OpenPGP implementation:
* `gpg --detach-sig <file>`
* `gpg --detach-sign <file> <file>.1.sig`
1. Create a signed git commit:
* `git commit -S -m "add <name> pgp key"`
1. Copy the updated ceremonies repo to the SD card
* `cp -r . /media/external/ceremonies`
1. Unplug the SD card from the air-gapped machine
1. Plug in the SD card into the online machine

2
quorum-vault-system/src/key-types.md
View File

@ -4,7 +4,7 @@
Used for day to day operations such as signing keys being added to keychain, signing tamper evidence, signing transaction requests and approvals etc.
When bootstrapping a system, the initial PGP keys can be generated on-board a smart card using [this guide](./generated-documents/all-levels/provision-pgp-signing-keys-on-board-smart-card.md).
When bootstrapping a system, the initial PGP keys can be generated using [this guide](./generated-documents/all-levels/pgp-key-provisioning.md).
### Requirements