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

personal pgp flow cleanup with issue docs

This commit is contained in:
Lance Vick 2025-02-11 18:59:59 -08:00
parent d0d6572dfa
commit e0600bbd50
Signed by: lrvick
GPG Key ID: 8E47A1EC35A1551D
5 changed files with 117 additions and 134 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
Makefile
View File

@ -16,7 +16,7 @@ out/qvs/index.json: out Containerfile.qvs $(shell find quorum-vault-system -type
. \
| tar -C out/qvs -mx
.PHONY: serve
.PHONY: serve-qvs
serve-qvs: build-qvs
tar -C out/qvs -cf - . | docker load
docker run -p $(PORT):8080 git.distrust.co/public/docs-qvs

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

@ -1,35 +1,27 @@
/* ANCHOR: all */
# Git Commit Signing
// ANCHOR: steps
1. Retrieve the value of your PGP key ID by using:
1. Retrieve the value of your PGP key ID from smartcard
* `gpg --list-keys`
1. Set up local `.gitconfig` file with desired PGP key:
```
[user]
name = <name>
email = <email>
signingKey = <pgp_key_id>
[commit]
gpgsign = true
merge = true
[core]
editor = "code --wait"
gpg --card-status
```
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
1. Configure git to sign commits with smartcard
```
$ git config --global user.name <name>
$ git config --global user.email <email>
$ git config --global user.signingKey <pgp_key_id>
$ git config --global commit.gpgsign = true
$ git config --global commit.merge = true
```
1. Configure ssh to authenticate with smartcard
```
$ echo 'export SSH_AUTH_SOCK="$(gpgconf --list-dirs agent-ssh-socket)"' > ~/.bashrc
$ source ~/.bashrc
```
Note: If you use another shell such as zsh, adjust acccordingly
// ANCHOR_END: steps
/* ANCHOR: all */

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

@ -8,40 +8,59 @@ as such need to be set up in a manner that minimizes exposure risks.
## Generating Keys using `keyfork` and `oct`
// ANCHOR: steps-keyfork
1. Insert an SD card into the system
1. Change working directory to SD card mount location
```
$ cd /media/TRANSFER
```
1. Insert a smartcard into the system, and get its ID:
* `smart_card_id="$(oct list -i | head -1)"`
a. Set variable with card ID
```
$ card_id="$(oct list -i | head -1)"`
```
b. Test the variable was set correctly
```
$ echo $card_id`
```
* You may test the variable was set correctly using `echo $smart_card_id` (tapping tab for auto-completion is helpful here)
1. Set the smart card to require touch for all operations
1. Set the smart card to require touch for all operations (defau admin PIN is 12345678):
* `oct admin --card $smart_card_id touch --key SIG --policy On`
* `oct admin --card $smart_card_id touch --key DEC --policy On`
* `oct admin --card $smart_card_id touch --key AUT --policy On`
* `oct admin --card $smart_card_id touch --key ATT --policy On`
```
$ oct admin --card $card_id touch --key SIG --policy On
$ oct admin --card $card_id touch --key DEC --policy On
$ oct admin --card $card_id touch --key AUT --policy On
$ oct admin --card $card_id touch --key ATT --policy On
```
Note: default admin PIN is 12345678
1. Generate a mnemonic, encrypting to a newly-generated key:
* `keyfork mnemonic generate --size 256 --encrypt-to-self cert.asc,output=encrypted-mnemonic.asc --provision openpgp-card,identifier="$smart_card_id"`
```
$ keyfork mnemonic generate --encrypt-to-self public.asc,output=private.asc --provision openpgp-card,identifier="$card_id"
```
* The PIN can't use sequential numbers, characters or repeated patterns.
Note: The PIN can't use sequential numbers, characters or repeated patterns.
1. If additional smart cards are required, recover the Keyfork key from the encrypted mnemonic:
1. Rename output to use key fingerprint:
* `gpg --import cert.asc`
```
$ fingerprint="$(sq keyring cert.asc | awk '{ print $2 }')"
$ mv public.asc "${fingerprint}.pub.asc"
$ mv private.asc "${fingerprint}.prv.asc"
```
* `gpg --decrypt encrypted-mnemonic.asc | KEYFORK_PROMPT_TYPE=headless keyfork recover mnemonic --daemon`
1. Optional: Create duplicate smartcards.
* Remove your previous key, and plug in the new key.
You can insert new smartcards and perform the following steps as needed:
* `smart_card_id="$(oct list -i | head -1)"`
* `keyfork provision openpgp-card --identifier "$smart_card_id" --account-id 0`
1. Insert an SD card to contain the public certificate and the encrypted mnemonic.
* `cp cert.asc encrypted-mnemonic.asc /media`
```
$ gpg --import *.pub.asc
$ gpg --decrypt *.prv.asc | KEYFORK_PROMPT_TYPE=headless keyfork recover mnemonic --daemon
$ keyfork provision openpgp-card --identifier "$(oct list -i | head -1)" --account-id 0
```
// ANCHOR_END: steps-keyfork

10
quorum-vault-system/src/component-documents/tamper-evidence-methods.md
View File

@ -131,15 +131,11 @@ Sealing bags of standard size objects which need to be protected can fit in. The
#### Unsealing
// ANCHOR: vsbwf-procedure-unsealing
1. Retrieve photographs of the top and the bottom of the object which were taken of the sealed object
a. Retrieve digital/physical photographs of both sides of sealed bundle
1. Compare printed photographs of object to the sealed object
b. Compare all photographs to object for differences
1. (IF polaroid photographs are available): Compare polaroid to the current state of the sealed object
1. (IF polaroid photographs are available): Compare polaroid to printed photographs
1. If there is no noticeable difference, proceed with unsealing the object, otherwise initiate an incident response process according to organization's policies.
c. Proceed with unsealing the object if no differences are detected
// ANCHOR_END: vsbwf-procedure-unsealing

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

@ -2,95 +2,73 @@
## Requirements
* 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)
* Provided by [AirGapped Bundle](../level-2/fixed-location/provisioner/air-gapped-bundle.md)
* Alternative: Create your own from documentation in [AirgapOS Repository](https://git.distrust.co/public/airgap)
* 2+ new smart cards
* AirgapOS Laptop
* Provided by [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))
* 2+ SD cards
* Linux Workstation
* Any internet connected Linux shell will suffice
## Generate OpenPGP Key
* 1 New Smart Card
* Nitrokey Pro 3+ or Yubikey 5+
1. If using AirGapped Bundle unseal first, otherwise proceed to step where AirgapOS SD card is inserted into computer
* 1 Transfer SD card
* Document will assume volume label is TRANSFER
* Brand and size does not matter
## Process
**Note: Most steps will simplified to a single command in a future iteration**
**See: [keyfork#73](https://git.distrust.co/public/keyfork/issues/73), [keyfork#74](https://git.distrust.co/public/keyfork/issues/74), [keyfork#76](https://git.distrust.co/public/keyfork/issues/76), [keyfork#77](https://git.distrust.co/public/keyfork/issues/77), [keyfork#78](https://git.distrust.co/public/keyfork/issues/78)**
1. If using pre-sealed Cold Bundle unseal as follows:
{{ #include ../../component-documents/tamper-evidence-methods.md:vsbwf-procedure-unsealing }}
1. Insert AirgapOS SD card into computer
1. Boot to AirgapOS
* Boot from the SD card by modifying the Boot Menu
* [Disabling secure boot](generated-documents/level-2/fixed-location/procurer/procure-tamper-proofing-equipment.html) may be necessary
1. Boot AirgapOS Laptop
{{ #include ../../component-documents/openpgp-setup.md:steps-keyfork}}
## Adding a OpenPGP Public Certificate to the Ceremony Repository
1. Power down AirgapOS Laptop
1. Switch to online machine
1. Switch to Linux Workstation
1. Open a terminal and navigate to the `vaults` repository or clone it:
1. Attach SD card from AirgapOS machine
* If already cloned: `cd ~/vaults`
1. Attach smartcard provisioned with AirgapOS machine
* If not, clone using: `cd ~ && git clone <vaults_repository_url>`
1. Import newly generated public key into local keychain
1. Ensure you are on the correct branch:
```
$ gpg --import /media/transport/*.pub.asc
```
* `git checkout main`
{{ #include ../../component-documents/git-commit-signing.md:steps }}
1. Pull the latest ceremony repo changes
1. Push new key material to Vaults repository
* `git pull origin main`
1. Ensure you have the certificate copied locally. If on an SD card, plug in the SD card and use the following steps to copy certificate to online machine:
* To copy from SD card:
{{ #include ../../component-documents/finding-device-name.md:content }}
* `cp /media/cert.asc ~/vaults`
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 }')"`
1. 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`
1. Export your OpenPGP public certificate:
* `gpg --export --armor <key_fingerprint> > <key_fingerprint>.asc`
1. Place the file in `keys/all/<key_fingerprint>.asc`
* `mv <key_fingerprint>.asc keys/all/`
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"`
1. Push to the commit:
* `git push origin main`
a. Clone repository (if not done previously)
```
$ git clone <vaults_repository_url> ~/vaults
```
b. Checkout main branch
```
$ cd ~/vaults
$ git checkout main
$ git pull origin main
```
b. Commit and push modifications
```
$ cp /media/TRANSFER/*.asc keys/all
$ git add .
$ git commit -S -m "add <name> pgp key"
$ git push origin main
```
1. Communicate your new key fingerprint to all other participants:
@ -98,9 +76,7 @@
* 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
1. Get confirmation they have imported your key to their keychains
## 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 }}
* e.g. `gpg --import <your_key_id>.asc`
* Confirm this is done for keyrings on workstations used to interact with the Vaults repository