many changes
This commit is contained in:
parent
c4ca2d3555
commit
22fa2404e5
GPG Key ID:
44A86CFF1FDF0E85
|
|
@ -16,7 +16,7 @@ This repository holds data pertaining to ceremonies. The primary data consists o
|
|||
|
||||
## Directives
|
||||
|
||||
* MUST be private
|
||||
* 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
|
||||
|
||||
|
|
@ -26,9 +26,12 @@ This repository holds data pertaining to ceremonies. The primary data consists o
|
|||
|
||||
```
|
||||
ceremonies/
|
||||
/<date>
|
||||
audit_log.txt
|
||||
<date>/
|
||||
log.txt
|
||||
- [ ] TODO: write a layout for the log
|
||||
tamper_evidence/
|
||||
<photo_name>.jpeg
|
||||
<photo_name>.jpeg
|
||||
transactions/
|
||||
<tx_name>.tx.json
|
||||
policies/
|
||||
|
|
|
|||
|
|
@ -3,6 +3,9 @@
|
|||
|
||||
The GitKraken tool can be used to produce commits with data.
|
||||
|
||||
- [ ] TODO deterministic build of GitKraken / custom tool for this
|
||||
- [ ] TODO maybe it's better to train the team to use `git` in the terminal for now until we have a better tool because GitKraken introduces a lot of surface area for attacks
|
||||
|
||||
# GitKraken Guide: Create a File, Edit in VS Code, and Commit
|
||||
// ANCHOR: steps
|
||||
1. Clone the Repository
|
||||
|
|
|
|||
|
|
@ -1 +1,35 @@
|
|||
/* ANCHOR: all */
|
||||
# Keychain Repository
|
||||
// ANCHOR: content
|
||||
This repository contains the trusted keys for the organization.
|
||||
|
||||
## Directives
|
||||
|
||||
* MUST be a private repository
|
||||
|
||||
* MUST require signed commits
|
||||
|
||||
## Repository Structure
|
||||
|
||||
trusted-keys/
|
||||
proposers/
|
||||
<key_id>/
|
||||
pub.asc
|
||||
sig_1.asc
|
||||
sig_2.asc
|
||||
approvers/
|
||||
operators/
|
||||
|
||||
## Procedure: Adding OpenPGP Keys
|
||||
|
||||
1. Designate the role of the key - it should be placed into the corresponding role directory
|
||||
|
||||
1. Open a PR submitting the key to the repository
|
||||
|
||||
* MUST be via commit signed by the PGP key being submitted to the repository
|
||||
|
||||
1. Two other authorized individuals (TODO define how they are authorized) must provide detached PGP signatures of the key being submitted
|
||||
|
||||
1. The PR should be merged using a signed commit via the git CLI
|
||||
// ANCHOR_END: content
|
||||
/* ANCHOR_END: all */
|
||||
|
|
@ -3,14 +3,133 @@
|
|||
|
||||
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
|
||||
## Generating Keys using `keyfork` and `openpgp-card-tools`
|
||||
// ANCHOR: steps-keyfork
|
||||
1. Generate a mnemonic:
|
||||
|
||||
1. Use keyfork to generate a key and provision a card
|
||||
* `keyfork mnemonic generate --size 256 > mnemonic.txt`
|
||||
|
||||
1. Encrypt the mnemonic to the generated key
|
||||
1. Write the mnemonic on a small piece of paper as you will need to enter the words in the next step. After entering the words, set the piece of paper on fire (that's why it should be small enough - to make burning it easy)
|
||||
|
||||
1. In a new terminal window start `keyfork` daemon with the mnemonic:
|
||||
|
||||
* `export KEYFORKD_SOCKET_PATH=/tmp/keyforkd.socket`
|
||||
|
||||
* `keyfork recover mnemonic`
|
||||
|
||||
* Enter the mnemonic as prompted
|
||||
|
||||
* ctrl + z
|
||||
|
||||
* `bg`
|
||||
|
||||
1. Derive PGP keypair:
|
||||
|
||||
* `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
|
||||
|
||||
* 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 }' > 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. Bundle all data and encrypt it
|
||||
|
||||
* `mkdir backup_bundle/`
|
||||
|
||||
* `mv pub.asc priv.asc smart-card-pin.txt backup_bundle/`
|
||||
|
||||
* `tar -cvf backup_bundle.tar backup_bundle/`
|
||||
|
||||
* `gpg --armor -er <pgp_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.
|
||||
|
||||
* `lsblk`
|
||||
|
||||
* `sudo mount /dev/<your_device> media/`
|
||||
|
||||
* `cp backup_bundle.tar.gpg /media`
|
||||
|
||||
1. For posterity, delete all the generated assets before shutting down
|
||||
computer;
|
||||
|
||||
* `rm -rf *`
|
||||
// ANCHOR_END: steps-keyfork
|
||||
|
||||
## Generating Keys on YubiKey
|
||||
// ANCHOR: steps-on-key-gen
|
||||
|
||||
1. Insert the YubiKey into the USB port if it is not already plugged in.
|
||||
|
||||
1. Open Command Prompt (Windows) or Terminal (macOS / Linux).
|
||||
|
||||
1. Enter the GPG command: gpg --card-edit
|
||||
|
||||
1. At the gpg/card> prompt, enter the command: admin
|
||||
|
||||
1. If you want to use keys larger than 2048 bits, run: key-attr
|
||||
|
||||
1. Enter the command: generate
|
||||
|
||||
1. When prompted, specify if you want to make an off-card backup of your encryption key.
|
||||
|
||||
* Note: This is a shim backup of the private key, not a full backup, and cannot be used to restore to a new YubiKey.
|
||||
|
||||
1. Specify how long the key should be valid for (specify the number in days, weeks, months, or years).
|
||||
|
||||
1. Confirm the expiration day.
|
||||
|
||||
1. When prompted, enter your name.
|
||||
|
||||
1. Enter your email address.
|
||||
|
||||
1. If needed, enter a comment.
|
||||
|
||||
1. Review the name and email, and accept or make changes.
|
||||
|
||||
1. Enter the default admin PIN again. The green light on the YubiKey will flash while the keys are being written.
|
||||
|
||||
1. Enter a Passphrase as the key will not allow you to pass without having a passphrase. If you do not enter a Passphrase generation will fail.
|
||||
// ANCHOR_END: steps-on-key-gen
|
||||
|
||||
1. [OPTIONAL]: The operator key can be encrypted to the organization [Disaster Recovery Public Certificate](TODO).
|
||||
// ANCHOR_END: steps
|
||||
/* ANCHOR_END: all */
|
||||
|
|
@ -2,22 +2,26 @@
|
|||
|
||||
The approver is responsible for verifying a transaction proposed by a [proposer](../../../../system-roles.md).
|
||||
|
||||
## Responsibilities
|
||||
## Requirements
|
||||
|
||||
* MUST verify the proposer data out of band (over a secure channel)
|
||||
* If necessary, provision a PGP key pair to a smart card using the guide in the [Appendix: Generating PGP Keypair & Provisioning Smart Card](#generating-pgp-keypair--provisioning-smart-card)
|
||||
|
||||
* Proposer data is primarily their PGP key
|
||||
* 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)
|
||||
|
||||
* MUST verify the PGP signature of the data according to a policy
|
||||
* Clone the [Ceremonies Repository](../../../../component-documents/ceremony-repository.md) for your organization to the machine
|
||||
|
||||
* TODO: specify how the policy works
|
||||
## Procedure
|
||||
|
||||
* MUST add their own well known PGP key signature to the data if the data is verified to be valid.
|
||||
1. Pull the latest changes from the `ceremonies` repository
|
||||
|
||||
* NOTE: all transaction values must be signed as part of a single message
|
||||
1. Verify the PGP key of the Proposer is valid
|
||||
|
||||
To sign the transaction payload and produce a detached signature use:
|
||||
1. Verify that the commit with the tx data is properly signed by the key that was verified in the previous step
|
||||
|
||||
`gpg --armor --output <approver.sig> --detach-sig <filename>`
|
||||
1. Verify that the transaction is according to the defined policy (TODO link to policy)
|
||||
|
||||
Transmit the `proposer.asc` and `approver.sig` to the operator.
|
||||
1. To sign the transaction payload and produce a detached signature use:
|
||||
|
||||
* `gpg --armor --output <approver.sig> --detach-sig <filename>`
|
||||
|
||||
1. Commit the detached signature alongside the tx
|
||||
|
|
|
|||
|
|
@ -20,53 +20,55 @@
|
|||
|
||||
* Write it down on a piece of paper as it will be used during the ceremony
|
||||
|
||||
|
||||
## 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.
|
||||
|
||||
- [ ] TODO guide on how to do this
|
||||
|
||||
1. Enter the designated location with the 3 operators and all required equipment
|
||||
|
||||
2. Lock access to the location - there should be no inflow or outflow of people during the ceremony
|
||||
1. Lock access to the location - there should be no inflow or outflow of people during the ceremony
|
||||
|
||||
3. Retrieve sealed laptop and polaroid from locked storage
|
||||
1. Retrieve sealed laptop and polaroid from locked storage
|
||||
|
||||
### Unsealing Tamper Proofing
|
||||
{{ #include ../../../../../../tamper-evidence-methods.md:vsbwf-procedure-unsealing}}
|
||||
|
||||
### Secure Boot Procedure
|
||||
0. Plug PureBoot smart card into air-gapped machine
|
||||
1. Plug PureBoot smart card into air-gapped machine
|
||||
|
||||
1. Plug in SD card labelled "AirgapOS"
|
||||
|
||||
{{ #include ../../../../../../secure-boot-sequence.md:prepared}}
|
||||
|
||||
0. Plug in SD card labelled "Trusted Keys"
|
||||
1. Plug in SD card labelled "Keychain"
|
||||
|
||||
* Load well known PGP keys of proposer and approver, and sign them using operator keys (NOT IMPLEMENTED)
|
||||
* Load well known PGP keys of proposer and approver along with detached signatures of the keys (NOT IMPLEMENTED)
|
||||
|
||||
* `gpg --import <keyfile_name>`
|
||||
|
||||
1. Insert SD card labelled "shardfile"
|
||||
|
||||
2. `keyfork recover shard --daemon`
|
||||
1. `keyfork recover shard --daemon`
|
||||
|
||||
* Follow on screen prompts
|
||||
|
||||
3. As a last step, run the `icepick` command which is awaiting the transaction payload
|
||||
1. As a last step, run the `icepick` command which is awaiting the transaction payload
|
||||
|
||||
* `icepick workflow sol-transfer`
|
||||
|
||||
* Follow on screen prompts
|
||||
|
||||
|
||||
### Obtain Transaction Request
|
||||
|
||||
1. Turn on online machine
|
||||
|
||||
2. Get transaction request(s)
|
||||
1. Get transaction request(s)
|
||||
|
||||
* TODO define means (could just be email?)
|
||||
|
||||
3. Run `icepick workflow sol-broadcast` command
|
||||
1. Run `icepick workflow sol-broadcast` command
|
||||
|
||||
* Wait for prompt and plug in fresh SD card
|
||||
|
||||
|
|
@ -74,13 +76,13 @@
|
|||
|
||||
* 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
|
||||
|
||||
5. Unplug the SD card and pass it to the air-gapped machine operators
|
||||
1. Unplug the SD card and pass it to the air-gapped machine operators
|
||||
|
||||
### Sign Transaction
|
||||
|
||||
1. Plug in SD card with transaction payload
|
||||
|
||||
2. Wait for the screen to display the transaction information. (NOT IMPLEMENTED)
|
||||
1. Wait for the screen to display the transaction information. (NOT IMPLEMENTED)
|
||||
|
||||
* In the background:
|
||||
|
||||
|
|
@ -88,25 +90,25 @@
|
|||
|
||||
* Signatures of tx data are verified against well known keys which were loaded by operators into local GPG keychain and signed by operators (NOT IMPLEMENTED)
|
||||
|
||||
3. If any issues are detected with data you will be prompted and should initiate [incident response (todo)](todo)
|
||||
1. If any issues are detected with data you will be prompted and should initiate [incident response (todo)](todo)
|
||||
|
||||
4. Wait for the "completed" message
|
||||
1. Wait for the "completed" message
|
||||
|
||||
5. Unplug and give the SD card back to the online machine operator
|
||||
1. Unplug and give the SD card back to the online machine operator
|
||||
|
||||
### Broadcast Transaction
|
||||
|
||||
* Online machine operator takes the SD card to online machine and plugs it in
|
||||
1. Online machine operator takes the SD card to online machine and plugs it in
|
||||
|
||||
* The still running process from running the command to create the transaction in [Obtain Transaction Request](#obtain-transaction-request) will broadcast the transaction automatically
|
||||
1. The still running process from running the command to create the transaction in [Obtain Transaction Request](#obtain-transaction-request) will broadcast the transaction automatically
|
||||
|
||||
* Await the "completed" message
|
||||
1. Await the "completed" message
|
||||
|
||||
### Finalization
|
||||
|
||||
* Shut down online machine
|
||||
1. Shut down online machine
|
||||
|
||||
* Shut down the air gapped machine
|
||||
1. Shut down the air gapped machine
|
||||
|
||||
#### Sealing
|
||||
|
||||
|
|
|
|||
|
|
@ -18,7 +18,7 @@ The proposer must combine these values into a single message, which can be a sim
|
|||
|
||||
## Requirements
|
||||
|
||||
* 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)
|
||||
* If necessary, provision a PGP key pair to a smart card using the guide in the [Appendix: Generating PGP Keypair & Provisioning Smart Card](#generating-pgp-keypair--provisioning-smart-card)
|
||||
|
||||
* 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)
|
||||
|
||||
|
|
@ -52,6 +52,7 @@ The proposer must combine these values into a single message, which can be a sim
|
|||
}
|
||||
```
|
||||
|
||||
// TODO using the git gui introduces a lot of risk, we can either use `git` to reduce risk, or audit and deterministically build a GUI tool like GitKraken
|
||||
{{ #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).
|
||||
|
|
@ -59,7 +60,7 @@ The proposer must combine these values into a single message, which can be a sim
|
|||
## Appendix
|
||||
|
||||
### Git Commit Signing Configuration
|
||||
|
||||
{{ #include ../../../../component-documents/git-commit-signing.md:steps }}
|
||||
|
||||
### Provisioning PGP Smart Card
|
||||
### Generating PGP Keypair & Provisioning Smart Card
|
||||
{{ #include ../../../../component-documents/openpgp-setup.md:steps-keyfork }}
|
||||
|
|
@ -0,0 +1,3 @@
|
|||
# Keychain Repository
|
||||
|
||||
{{ #include ../../../../component-documents/keychain-repository.md:content }}
|
||||
|
|
@ -1,2 +0,0 @@
|
|||
# Trusted Keys Repository
|
||||
todo
|
||||
|
|
@ -65,8 +65,6 @@ or the [One Time Use Airgap-OS](one-time-use-airgapos.md)
|
|||
|
||||
* `keyfork mnemonic generate --size 256 | awk '{ print $1, $2, $3, $4, $5 }' > smart-card-pin.txt`
|
||||
|
||||
* `cat smart-card-pin.txt`
|
||||
|
||||
* `oct pin --card <smart_card_id> set-user`
|
||||
|
||||
* Enter the <smart_card_pin>
|
||||
|
|
|
|||
Loading…
Reference in New Issue