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

many usability improvements

This commit is contained in:
Anton Livaja 2025-01-31 04:32:50 -05:00
parent 759cd4339f 35b1d668c6
commit f7e119d5c4
Signed by: anton
GPG Key ID: 44A86CFF1FDF0E85
17 changed files with 209 additions and 69 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -31,8 +31,6 @@
* [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)
<<<<<<< HEAD
* [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)
>>>>>>> feat/encrypt-wallet-to-namespace
* [Export Namespace Mnemonic](generated-documents/level-2/fixed-location/operator/export-namespace-mnemonic.md)

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

@ -10,7 +10,9 @@ This repository holds data pertaining to ceremonies. The primary data consists o
* Trusted PGP keyring
* Shardfile
* Shardfiles
* Blockchain metadata
* Policies (such as spending rules)
@ -20,8 +22,6 @@ This repository holds data pertaining to ceremonies. The primary data consists o
* MUST be a private repository
* MUST be write protected, requiring approval from at least 1 individual other than one who opened the PR for merging
* MUST require signed commits
## Repository Structure

6
quorum-vault-system/src/component-documents/finding-device-name.md Normal file
View File

@ -0,0 +1,6 @@
/* ANCHOR: all */
// ANCHOR: content
Look for your SD card device name (`<device_name>`) 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`)
* You may mount the device using: `sudo mount /dev/<your_device> media/`
// ANCHOR_END: content
/* ANCHOR_END: all */

2
quorum-vault-system/src/component-documents/git-commit-signing.md
View File

@ -3,7 +3,7 @@
// ANCHOR: steps
1. Retrieve the value of your PGP key ID by using:
`gpg --list-keys`
* `gpg --list-keys`
1. Set up local `.gitconfig` file with desired PGP key:
```

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

@ -31,11 +31,9 @@ as such need to be set up in a manner that minimizes exposure risks.
1. Insert an SD card to contain the public certificate and the encrypted mnemonic.
* `lsblk`
* {{ #include finding-device-name.md:content}}
* `sudo mount /dev/<your_device> media/`
* `cp cert.asc encrypted-mnemonic.asc /media`
* `cp cert.asc encrypted-mnemonic.asc /media/<device_name>/`
// ANCHOR_END: steps-keyfork

16
quorum-vault-system/src/component-documents/sd-formatting.md
View File

@ -4,27 +4,23 @@
* microSD or standard SD card can be used
2. Launch a terminal
1. Launch a terminal
3. List all block devices, including your SD card:
1. {{ #include finding-device-name.md: content }}
* `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:
1. 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):
1. 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.vfat /dev/sdX`
7. You can verify that the SD card has been formatted by running lsblk again or by checking the file system type:
1. 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:
1. Once formatting is complete, you can safely remove physically or eject the SD card:
* `sudo eject /dev/sdX`
//ANCHOR_END:steps

3
quorum-vault-system/src/component-documents/storage-device-management.md
View File

@ -9,8 +9,7 @@ USB devices are assigned names when they are connected to a Linux operating
system. The first storage device is assigned the name `sda` (storage device a),
the second `sdb`, the third `sdc` and so on.
One may use the `lsblk` to list the detected storage devices for a system, which
will output something like this:
One may use the `lsblk` to list the detected storage devices for a system, which will output something like this:
```
NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT
xvda 202:0 1 50G 0 disk

18
quorum-vault-system/src/generated-documents/all-levels/pgp-key-provisioning.md
View File

@ -2,7 +2,10 @@
## Requirements
* Computer that can load AirgapOS ([compatibility reference](https://git.distrust.co/public/airgap#tested-models))
* Computer
* Preferred: [AirGapped Bundle](../level-2/fixed-location/provisioner/air-gapped-bundle.md)
* Alternative: Computer that can load AirgapOS ([compatibility reference](https://git.distrust.co/public/airgap#tested-models))
* [AirgapOS SD card](../level-2/fixed-location/provisioner/provision-airgapos.md)
@ -12,6 +15,10 @@
## Generate OpenPGP Key
1. If using AirGapped Bundle unseal first, otherwise proceed to step where AirgapOS SD card is inserted into computer
{{ #include ../../component-documents/tamper-evidence-methods.md:vsbwf-procedure-unsealing }}
1. Insert AirgapOS SD card into computer
1. Boot to AirgapOS
@ -54,6 +61,10 @@
1. Place the file in `keys/all/<key_fingerprint>.asc`
1. Stage the modified file:
* `git add keys/all/<key_fingerprint>.asc`
1. Create signed git commit:
* `git commit -S -m "add <name> pgp key"`
@ -69,3 +80,8 @@
* Fallback: via two logically distinct online communications methods (e.g. encrypted chat, and video call)
1. Get confirmation they have used `gpg --import <your_key_id>.asc` to import your key from the git repo to the keyrings on workstations they will use to interact with the ceremony repo
## Local Configurations for OpenPGP
This configuration enables the use of smart cards for OpenPGP operations, and enforces git commit signing.
{{ #include ../../component-documents/git-commit-signing.md:steps }}

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

@ -46,15 +46,27 @@ The approver is responsible for verifying a transaction proposed by a [proposer]
1. Plug in the Ceremony SD card
1. {{ #include ../../../../component-documents/finding-device-names.md:content }}
1. Plug in the Operator smart card
1. Set a local variable `pgp_key_id` to the smart card OpenPGP key id:
* `pgp_key_id="$(oct list -i | head -1)`
1. Copy the git repo locally from the Ceremony SD card
* `cp -r /media/external/ceremonies /root/ceremonies; cd /root/ceremonies`
* `cp -r /media/<device_name>/ceremonies /root/ceremonies`
1. Change directory to ceremonies
* `cd /root/ceremonies`
1. Verify the detached signature for the payload
* `gpg --verify <filename> <filename>.1.sig`
* `gpg --verify <payload>.<num>.json <payload>.<num>.<key_id>.sig`
* The filename will be of format: `keys/ceremonies/<date>/payloads/payload_<number>.json`
* The filename will be of format: `/<namespace>/ceremonies/<date>/payloads/payload_<number>.json`
1. Verify the key is authenticated:
@ -64,28 +76,42 @@ The approver is responsible for verifying a transaction proposed by a [proposer]
1. Sign the transaction payload:
* `gpg --detach-sign <filename> > <filename>.2.sig`
* `gpg --detach-sign <namespace>/ceremonies/<date>/payloads/payload_<num>.json > <namespace>/ceremonies/<date>/payloads/payload_<num>_$pgp_key_id.sig`
* e.g `gpg --detach-sign solana-01/ceremonies/2025-01-01/payloads/payload_1.json > solana-01/ceremonies/2025-01-01/payloads/payload_1_F4BF5C81EC78A5DD341C91EEDC4B7D1F52E0BA4D.sig`
1. Stage the modified file:
* `git add <namespace>/ceremonies/<date>/payloads/payload_<num>_$pgp_key_id.sig`
1. Create a signed git commit:
* `git commit -S -m "add <name> pgp key"`
* `git commit -S -m "add payload signature for payload_<num>.json using $pgp_key_id"`
1. {{ #include ../../../../component-documents/finding-device-names.md:content }}
1. Copy the updated ceremonies repo to the SD card
* `cp -r . /media/external/ceremonies`
* `cp -r /root/ceremonies /media/<device_name>/ceremonies`
1. Unplug the SD card from the air-gapped machine
1. Plug in the SD card into the online machine
1. {{ #include ../../../../component-documents/finding-device-name.md:content }}
1. Copy the updated repository locally:
* `cp -r /media/<device_name>/ceremonies ~/`
1. Change into locally copied directory
* `cd ~/ceremonies`
1. Push the latest commit to the repository
* `git push origin main`
1. Tamper proof the AirgapOS and Air-gapped laptop
{{ #include ../../../../component-documents/tamper-evidence-methods.md:vsbwf-procedure-sealing}}
## Appendix
### Git Commit Signing Configuration
{{ #include ../../../../component-documents/git-commit-signing.md:steps }}

4
quorum-vault-system/src/generated-documents/level-2/fixed-location/operator/ceremony-sd-card-provisioning.md
View File

@ -20,11 +20,11 @@
1. Navigate to the ceremony repository for the ceremony being executed
1. Find the SD cards device name using `lsblk`
* {{ #include ../../../../component-documents/finding-device-name.md:content }}
1. Write the ceremony repo data to the SD card:
`cp ceremonies/ /media/<device_name>`
`cp -r ceremonies/ /media/<device_name>/`
1. Unplug the SD card

4
quorum-vault-system/src/generated-documents/level-2/fixed-location/operator/decrypt-namespace-secret.md
View File

@ -30,7 +30,7 @@
1. Copy the Ceremony SD Card contents to machine
* Find device name using `lsblk`
* {{ #include ../../../../component-documents/finding-device-name.md:content }}
* Copy the contents of the card to machine:
@ -38,7 +38,7 @@
1. Start `keyfork` using the relevant Shardfile:
* `keyfork recover shard --daemon /media/<media_name>/path/to/shardfile.asc`
* `keyfork recover shard --daemon /media/<device_name>/path/to/shardfile.asc`
* Follow on screen prompts

59
quorum-vault-system/src/generated-documents/level-2/fixed-location/operator/export-namespace-mnemonic.md Normal file
View File

@ -0,0 +1,59 @@
# Export Namespace Mnemonic
## Requirements
{{ #include ../../operator-requirements.md:requirements }}
* [SD Card Pack](../procurer/procure-sd-card-pack.md)
* [Ceremony SD Card](../operator/ceremony-sd-card-provisioning.md)
* [High Visibility Storage](TODO): plastic container or bag that's used to keep items while not in use in a visible location like the middle of a desk.
## Procedure
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. Place Ceremony SD card in High Visibility Storage
1. Retrieve sealed Air-Gapped bundle, polaroid of tamper evidence, and online laptop from locked storage
{{ #include ../../../../component-documents/tamper-evidence-methods.md:vsbwf-procedure-unsealing}}
1. Place all contents except for the laptop into High Visibility Storage
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. Retrieve Ceremony SD card from High Visibility Storage and plug it into the air-gapped machine
1. Recover the mnemonic from an existing shardfile
* {{ #include ../../../../component-documents/finding-device-name.md:content }}
* `keyfork shard combine /media/<device_name>/shard.asc | keyfork-mnemonic-from-seed`
1. Follow on screen prompts
1. Unplug the Ceremony SD card and place it in High Visibility Storage
1. Unseal the SD Card Pack
{{ #include ../../../../component-documents/tamper-evidence-methods.md:vsbwf-procedure-unsealing}}
1. Put the mnemonic on an SD card for transport or use `cat` command to output it in the terminal for entry into a hardware wallet or otherwise
1. Shut down the air gapped machine
1. Gather all the original items that were in the air-gapped bundle:
* Air-gapped computer
* AirgapOS SD card
{{ #include ../../../../component-documents/tamper-evidence-methods.md:vsbwf-procedure-sealing}}

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

@ -44,17 +44,17 @@ This is a ceremony for generating and sharding entropy to a set of existing Quor
1. Back up the newly generated artifacts to any desired number of SD cards, and label each "Shardfile [unique_name] [date]"
1. `lsblk` to find media name
1. {{ #include ../../../../component-documents/finding-device-name.md:content }}
1. Back up the output shardfile:
* `cp shardfile.new.asc /media/<media_name>/`
* `cp shardfile.new.asc /media/<device_name>/`
1. Back up the new keyring file:
* `cp keyring.new.asc /media/<media_name>/`
* `cp keyring.new.asc /media/<device_name>/`
1. Back up the root PGP certificate:
* `cp root_pgp_cert.asc /media/<media_name>/`
* `cp root_pgp_cert.asc /media/<device_name>/`
1. Each backup should be placed into High Visibility Storage after it's made

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

@ -46,19 +46,19 @@ This is a ceremony for generating entropy which is used to derive Quorum PGP key
1. Plug in SD cards one at a time and use following steps to back up ceremony artifacts
1. Find media name using `lsblk`
1. {{ #include ../../../../component-documents/finding-device-name.md:content }}
1. Back up the root OpenPGP certificate
* `cp encryption_cert.asc /media/<media_name>/`
* `cp encryption_cert.asc /media/<device_name>/`
1. Back up the `shardfile.asc`
* `cp shardfile.asc /media/<media_name>/`
* `cp shardfile.asc /media/<device_name>/`
1. Back up the `keyring.asc`
* `cp keyring.asc /media/<media_name>/`
* `cp keyring.asc /media/<device_name>/`
1. Unplug the SD card and place it in High Visibility Storage

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

@ -20,7 +20,6 @@ The proposer must combine these values into a JSON file, such as:
}
```
## Requirements
* [Quorum PGP Key](../operator/quorum-entropy-ceremony.md)
@ -35,22 +34,32 @@ The proposer must combine these values into a JSON file, such as:
* Ensure that the computer is configured to sign commits with the desired key. Refer to the [Appendix: Git Commit Signing Configuration](#git-commit-signing-configuration)
* Clone the [Ceremonies Repository](../provisioner/provision-ceremonies-repository.md) for your organization to the machine
* Organization's Ceremonies repository git url
## Procedure
1. Turn on online machine
1. Clone the repository if it's not available locally:
* `git clone <repository_git_url>`
1. Pull the latest changes from the `ceremonies` repository
* `git pull origin main`
1. Unseal the SD Card Pack
{{ #include ../../../../component-documents/tamper-evidence-methods.md:vsbwf-procedure-unsealing}}
1. Plug a fresh SD card into the online machine
1. {{ #include ../../../../component-documents/finding-device-name.md:content }}
1. Save the ceremonies repo to the SD card, referred to as the Ceremony SD card
* `cp -r ~/ceremonies/ /media/<device_name>/`
1. Unplug the Ceremony SD card
1. Unseal the tamper proofed bundle
@ -63,18 +72,38 @@ The proposer must combine these values into a JSON file, such as:
1. Plug in the Ceremony SD card
1. {{ #include ../../../../component-documents/finding-device-name.md:content }}
1. Plug in the Operator smart card
1. Set a local variable `pgp_key_id` to the smart card OpenPGP key id:
* `pgp_key_id="$(oct list -i | head -1)`
1. Copy the git repo locally from the Ceremony SD card
* `cp -r /media/external/ceremonies /root/ceremonies; cd /root/ceremonies`
* `cp -r /media/<device_name>/ceremonies /root/ceremonies`
1. Change into the ceremonies directory:
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/`
* `cd /root/ceremonies`
* `mkdir -p keys/ceremonies/2024-01-01/payloads`
1. Create a new payloads directory in the `ceremonies` repository for the date on which the ceremony for the transaction will take place if it doesn't already exist
1. Determine a new filename `payload_<num>.json`, for example `payload_1.json`
* `mkdir -p <namespace>/ceremonies/<date>/payloads`
* e.g `mkdir -p solana-01/ceremonies/2025-01-01/payloads`
1. Create a new file `payload_<num>.json`, for example `payload_1.json`
* `touch <namespace>/ceremonies/<date>/payloads/payload_<num>.json`
* e.g `touch solana-01/ceremonies/2025-01-01/payloads/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.
* Write the data to the file: `vim <namespace>/ceremonies/<date>/payloads/payload_<num>.json`
```json
{
"workflow": ["<workflow_namespace>", "<workflow_name>"],
@ -100,37 +129,50 @@ The proposer must combine these values into a JSON file, such as:
"proposal_datetime": "2025-01-28T18:18:00"
}
```
1. Import the keys relevant to the ceremony:
* `gpg --import keys/all/*.asc`
* `gpg --import <namespace>/keyring.asc`
1. Sign the data in the CLI using `gpg` or another OpenPGP implementation:
* `gpg --detach-sign <file> <file>.1.sig`
* `gpg --detach-sign <namespace>/ceremonies/<date>/payloads/<payload>_<num>.json > <namespace>/ceremonies/<date>/payloads/payload_<num>_$pgp_key_id.sig`
* e.g `gpg --detach-sign solana-01/ceremonies/2025-01-01/payloads/payload_1.json > solana-01/ceremonies/2025-01-01/payloads/payload_1_F4BF5C81EC78A5DD341C91EEDC4B7D1F52E0BA4D.sig`
1. Stage the new file:
* `git add <namespace>/ceremonies/<date>/payloads/<payload>.<num>.$pgp_key_id.sig`
1. Create a signed git commit:
* `git commit -S -m "add payload signature for payload_<num>.sig using $pgp_key_id"`
1. {{ #include ../../../../component-documents/finding-device-name.md:content }}
1. Copy the updated ceremonies repo to the SD card
* `cp -r . /media/external/ceremonies`
* `cp -r /root/ceremonies /media/<device_name>/ceremonies`
1. Unplug the SD card from the air-gapped machine
1. Plug in the SD card into the online machine
1. Create a signed git commit:
1. {{ #include ../../../../component-documents/finding-device-name.md:content }}
* `git commit -S -m "add <name> pgp key"`
1. Copy the updated repository locally:
* `cp -r /media/<device_name>/ceremonies ~/`
1. Change into locally copied directory
* `cd ~/ceremonies`
1. Push the latest commit to the repository
* `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.
1. Tamper proof the AirgapOS and Air-gapped laptop
{{ #include ../../../../component-documents/tamper-evidence-methods.md:vsbwf-procedure-sealing}}
## Appendix
### Git Commit Signing Configuration
{{ #include ../../../../component-documents/git-commit-signing.md:steps }}

4
quorum-vault-system/src/generated-documents/level-2/fixed-location/provisioner/provision-airgapos.md
View File

@ -32,7 +32,7 @@
1. Retrieve a labelled SD card from High Visibility Storage, and plug it into the computer where AirgapOS will be built
1. 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`)
1. {{ #include ../../../../component-documents/finding-device-name.md:content }}
1. Flash `airgap.iso` to an SD Card:
@ -42,7 +42,7 @@
1. Once booted, the card needs to be locked using `sdtool` which is available in `AirgapOS`:
* Find out the block device name using `lsblk`
* {{ #include ../../../../component-documents/finding-device-name.md:content }}
* Note: the device will not mount as a proper block device on QubesOS so a different OS has to be used where the device appears as /dev/mmcblk<num>

2
quorum-vault-system/src/sdtool-instructions.md
View File

@ -19,7 +19,7 @@ This tool is also available via [stagex](https://registry.hub.docker.com/r/stage
* 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
1. Use `lsblk` to figure out the SD card device name
1. {{ #include finding-device-name.md:content }}
* Note: the device will not mount as a proper block device on QubesOS so a different OS has to be used where the device appears as /dev/mmcblk<num>