From c4ca2d35551ca8b56aa0eb396e4de34c2d752ed3 Mon Sep 17 00:00:00 2001 From: Anton Livaja Date: Fri, 20 Dec 2024 12:12:31 -0500 Subject: [PATCH] add content and related docs for proposer role --- quorum-key-management/src/SUMMARY.md | 8 ++- .../ceremony-repository.md | 38 ++++++++++++ .../component-documents/git-commit-signing.md | 35 +++++++++++ .../src/component-documents/gui-git-commit.md | 55 +++++++++++++++++ .../keychain-repository.md | 1 + .../src/component-documents/openpgp-setup.md | 16 +++++ ...-location-reusable-hardware-procurement.md | 1 + .../coins/pyth-spl/sign-transaction.md | 5 +- .../proposer/create-transaction-payload.md | 59 +++++++++++++++---- .../provisioner/ceremonies-repository.md | 3 + .../provisioner/trusted-keys-repository.md | 2 + ...rdware-procurement-and-chain-of-custody.md | 2 +- .../src/initialize-pureboot-smart-card.md | 2 + 13 files changed, 212 insertions(+), 15 deletions(-) create mode 100644 quorum-key-management/src/component-documents/ceremony-repository.md create mode 100644 quorum-key-management/src/component-documents/git-commit-signing.md create mode 100644 quorum-key-management/src/component-documents/gui-git-commit.md create mode 100644 quorum-key-management/src/component-documents/keychain-repository.md create mode 100644 quorum-key-management/src/component-documents/openpgp-setup.md create mode 100644 quorum-key-management/src/generated-documents/level-2/fixed-location/provisioner/ceremonies-repository.md create mode 100644 quorum-key-management/src/generated-documents/level-2/fixed-location/provisioner/trusted-keys-repository.md diff --git a/quorum-key-management/src/SUMMARY.md b/quorum-key-management/src/SUMMARY.md index ab518e8..f93cf1d 100644 --- a/quorum-key-management/src/SUMMARY.md +++ b/quorum-key-management/src/SUMMARY.md @@ -63,6 +63,7 @@ * [Fixed-Location]() * [Provisioner](system-roles.md) * [Procure Equipment & Location](generated-documents/level-2/fixed-location/provisioner/procure-equipment-and-location.md) + * [Ceremony Repository](generated-documents/level-2/fixed-location/provisioner/ceremonies-repository.md) * [Proposer](system-roles.md) * [Propose Transaction](generated-documents/level-2/fixed-location/proposer/create-transaction-payload.md) * [Approver](system-roles.md) @@ -70,4 +71,9 @@ * [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]() \ No newline at end of file + * [Level 4]() + +* [Document Components]() + * [Git Commit Signing](./component-documents/git-commit-signing.md) + * [GUI Git Commit](./component-documents/gui-git-commit.md) + * [OpenPGP Setup](./component-documents/openpgp-setup.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 new file mode 100644 index 0000000..f8d1077 --- /dev/null +++ b/quorum-key-management/src/component-documents/ceremony-repository.md @@ -0,0 +1,38 @@ +/* ANCHOR: all */ +# Ceremony Repository + +// ANCHOR: content +This repository holds data pertaining to ceremonies. The primary data consists of: + +* Transaction proposals + +* Transaction approvals + +* Tamper proofing evidence + +* Policies (such as spending rules) + +* Participants + +## Directives + +* MUST be private + +* 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 + +``` +ceremonies/ + / + audit_log.txt + tamper_evidence/ + transactions/ + .tx.json +policies/ + spending-policy.json +``` +// ANCHOR_END: content +/* ANCHOR_END: all */ \ No newline at end of file diff --git a/quorum-key-management/src/component-documents/git-commit-signing.md b/quorum-key-management/src/component-documents/git-commit-signing.md new file mode 100644 index 0000000..e80f437 --- /dev/null +++ b/quorum-key-management/src/component-documents/git-commit-signing.md @@ -0,0 +1,35 @@ +/* ANCHOR: all */ +# Git Commit Signing +// ANCHOR: steps +1. Retrieve the value of your PGP key ID by using: + + `gpg --list-keys` + +1. Set up local `.gitconfig` file with desired PGP key: + ``` + [user] + name = + email = + signingKey = + + [commit] + gpgsign = true + merge = true + [core] + editor = "code --wait" + ``` + +1. Set up environment variables for using smart cards + + Open the `~/.bashrc` file and add the following content at the end: + + ```bash + if [ "${gnupg_SSH_AUTH_SOCK_by:-0}" -ne $$ ]; then + export SSH_AUTH_SOCK="$(gpgconf --list-dirs agent-ssh-socket)" + fi + + GPG_TTY=$(tty) + export GPG_TTY + ``` +// ANCHOR_END: steps +/* ANCHOR: all */ diff --git a/quorum-key-management/src/component-documents/gui-git-commit.md b/quorum-key-management/src/component-documents/gui-git-commit.md new file mode 100644 index 0000000..16f95a3 --- /dev/null +++ b/quorum-key-management/src/component-documents/gui-git-commit.md @@ -0,0 +1,55 @@ +/* ANCHOR: all */ +# Committing Using Git Graphical User Interface + +The GitKraken tool can be used to produce commits with data. + +# GitKraken Guide: Create a File, Edit in VS Code, and Commit +// ANCHOR: steps +1. Clone the Repository + * Launch the GitKraken application. + * Clone the ceremony repository: + * Click on the **"Clone"** button on the left sidebar. + * Enter the repository URL you want to clone. + * Choose a local directory where you want to save the repository. + * Click **"Clone the repo"**. + +1. Create a new file + * **Navigate to the repository**: Make sure you are in the cloned repository in GitKraken. + * **Create a new file**: + * Right-click on the folder where you want to create the file in the left sidebar. + * Select **"New File"**. + * Name your file (e.g., ``). + +1. Open the File in Visual Studio Code + * **Open Visual Studio Code**: + * Right-click on the newly created file + * Select **"Open in External Editor"** (this should open the file in Visual Studio Code) + +1. Add content to the file + * In Visual Studio Code, type a simple JSON blob. For example: + ```json + { + "name": "Sample", + "version": "1.0.0", + "description": "This is a sample JSON blob." + } + ``` + * Save the file: Press `Ctrl + S` (or `Cmd + S` on Mac) to save the changes. + +1. Stage the changes + * **Return to GitKraken**: Go back to GitKraken. + * **Stage the File**: + * In the left sidebar, you will see the file you just created under the **"Unstaged Files"** section. + * Click the checkbox next to `` to stage the file. + +1. Commit the Changes + * **Commit the Changes**: + * In the commit message box at the bottom, type a commit message (e.g., "Add with sample JSON blob"). + * Click the **"Commit changes"** button. + +1. Push the Changes (if needed) + * Push to remote repository: + * If you want to push your changes to the remote repository, click the **"Push"** button in the top toolbar. +// ANCHOR_END: steps + +/* ANCHOR_END: all */ \ No newline at end of file diff --git a/quorum-key-management/src/component-documents/keychain-repository.md b/quorum-key-management/src/component-documents/keychain-repository.md new file mode 100644 index 0000000..5eeb0d3 --- /dev/null +++ b/quorum-key-management/src/component-documents/keychain-repository.md @@ -0,0 +1 @@ +# Keychain Repository \ No newline at end of file diff --git a/quorum-key-management/src/component-documents/openpgp-setup.md b/quorum-key-management/src/component-documents/openpgp-setup.md new file mode 100644 index 0000000..eb81c79 --- /dev/null +++ b/quorum-key-management/src/component-documents/openpgp-setup.md @@ -0,0 +1,16 @@ +/* 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. + +## Procedure +// ANCHOR: steps +1. Secure an airgapped machine set up with AirgapOS + +1. Use keyfork to generate a key and provision a card + +1. Encrypt the mnemonic to the generated key + +1. [OPTIONAL]: The operator key can be encrypted to the organization [Disaster Recovery Public Certificate](TODO). +// ANCHOR_END: steps +/* ANCHOR_END: all */ \ No newline at end of file diff --git a/quorum-key-management/src/fixed-location-reusable-hardware-procurement.md b/quorum-key-management/src/fixed-location-reusable-hardware-procurement.md index 192eedc..a060c61 100644 --- a/quorum-key-management/src/fixed-location-reusable-hardware-procurement.md +++ b/quorum-key-management/src/fixed-location-reusable-hardware-procurement.md @@ -1,4 +1,5 @@ # Procure Hardware +- [ ] TODO update this doc so it listes a bunch of models that support pureboot, not just purism 1. Select a librem 14 laptop from https://puri.sm, and ensure: 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 1a979b3..c17a9e0 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 @@ -5,15 +5,16 @@ ## Requirements * Ensure both primary operators have their [Operator Keys](../../../../../../glossary.md#operator-key) - +- [ ] TODO define guide for setting up operator keys * 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 + - [ ] TODO: where do we refer to permitted PGP keys * Each operator should hash the `keychain` repository + - [ ] TODO define keychain repository setup * `sha256sum keychain/` diff --git a/quorum-key-management/src/generated-documents/level-2/fixed-location/proposer/create-transaction-payload.md b/quorum-key-management/src/generated-documents/level-2/fixed-location/proposer/create-transaction-payload.md index 778e62b..88460af 100644 --- a/quorum-key-management/src/generated-documents/level-2/fixed-location/proposer/create-transaction-payload.md +++ b/quorum-key-management/src/generated-documents/level-2/fixed-location/proposer/create-transaction-payload.md @@ -4,7 +4,7 @@ The proposer is a fiduciary whose responsibility is to make sound financial deci The proposer MUST clearly define, at a minimum: -* Token Name (SOL, PYTH-SPL, ETH, BTC etc.) +* Token Name (SOL, PYTH-SPL, ETH, ETH-PYTH, BTC etc.) * FROM address @@ -12,17 +12,54 @@ The proposer MUST clearly define, at a minimum: * 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. -```json -{ - "from-address": "
", - "to-address": "
", - "token-name": "", - "token-amount": "" -} -``` +## Requirements -To sign use the command: +* If necessary, provision a PGP key pair to a smart card using the guied in the [Appendix: Provisioning PGP Smart Card](#provisioning-pgp-smart-card) -`gpg --clearsign ` \ No newline at end of file +* 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](../../../../component-documents/ceremony-repository.md) for your organization to the machine + +## Procedure + +1. Define a new file "-.tx.json", for example "16:40-PYTH-SPL.tx.json" + +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/` + +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": "", + "token-amount": "", + "from-address": "
", + "to-address": "
", + "datetime": "" + } + ``` + + Example data object: + ```json + { + "token-name": "PYTH-SLN", + "token-amount": "42", + "from_address": "2Z72E62atYfpatQeqPvHZMaabmuz664xq5MRWv9xM5NX", + "to_address": "BNQr6T2UAuEPux1fuiygM6chrT5GkHKaMWeTTaRLmR7g", + "datetime": "" + } + ``` + +{{ #include ../../../../component-documents/gui-git-commit.md:steps}} + +6. 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(TODO). + +## Appendix + +### Git Commit Signing Configuration + +{{ #include ../../../../component-documents/git-commit-signing.md:steps }} + +### Provisioning PGP Smart Card \ No newline at end of file diff --git a/quorum-key-management/src/generated-documents/level-2/fixed-location/provisioner/ceremonies-repository.md b/quorum-key-management/src/generated-documents/level-2/fixed-location/provisioner/ceremonies-repository.md new file mode 100644 index 0000000..812f408 --- /dev/null +++ b/quorum-key-management/src/generated-documents/level-2/fixed-location/provisioner/ceremonies-repository.md @@ -0,0 +1,3 @@ +# Ceremonies Repository + +{{ #include ../../../../component-documents/ceremony-repository.md:content }} \ No newline at end of file diff --git a/quorum-key-management/src/generated-documents/level-2/fixed-location/provisioner/trusted-keys-repository.md b/quorum-key-management/src/generated-documents/level-2/fixed-location/provisioner/trusted-keys-repository.md new file mode 100644 index 0000000..890d34e --- /dev/null +++ b/quorum-key-management/src/generated-documents/level-2/fixed-location/provisioner/trusted-keys-repository.md @@ -0,0 +1,2 @@ +# Trusted Keys Repository +todo \ No newline at end of file diff --git a/quorum-key-management/src/hardware-procurement-and-chain-of-custody.md b/quorum-key-management/src/hardware-procurement-and-chain-of-custody.md index f7a93ef..4bda252 100644 --- a/quorum-key-management/src/hardware-procurement-and-chain-of-custody.md +++ b/quorum-key-management/src/hardware-procurement-and-chain-of-custody.md @@ -9,7 +9,7 @@ All steps of the provisioning process need to be completed under the supervision The following steps must all be completed under the continued supervision and with the involvement of all parties present. It is instrumental that there is not a single moment where the device is left unsupervised, or under the supervision of only 1 individual. -## Provisioning Hardware +## Provisioning Equipment // ANCHOR: steps 1. Selecting a Purchase Location diff --git a/quorum-key-management/src/initialize-pureboot-smart-card.md b/quorum-key-management/src/initialize-pureboot-smart-card.md index eebe00b..d426485 100644 --- a/quorum-key-management/src/initialize-pureboot-smart-card.md +++ b/quorum-key-management/src/initialize-pureboot-smart-card.md @@ -1,5 +1,7 @@ # PureBoot Setup +- [ ] TODO: fix this doc to use a different smart card for pureboot as the librem key, as the librem key doesn't have a physical switch + This guide walks the user through setting up a machine which relies on [PureBoot](https://source.puri.sm/firmware/pureboot) to verify the authenticity of the `.iso` image which is being booted, as well to ensure that firmware of