diff --git a/Makefile b/Makefile index b1e1095..20ce22a 100644 --- a/Makefile +++ b/Makefile @@ -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 diff --git a/quorum-vault-system/src/component-documents/git-commit-signing.md b/quorum-vault-system/src/component-documents/git-commit-signing.md index 030113f..7822507 100644 --- a/quorum-vault-system/src/component-documents/git-commit-signing.md +++ b/quorum-vault-system/src/component-documents/git-commit-signing.md @@ -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 = - email = - signingKey = - - [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 + $ git config --global user.email + $ git config --global user.signingKey + $ 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 */ diff --git a/quorum-vault-system/src/component-documents/openpgp-setup.md b/quorum-vault-system/src/component-documents/openpgp-setup.md index e939256..f9c9aa7 100644 --- a/quorum-vault-system/src/component-documents/openpgp-setup.md +++ b/quorum-vault-system/src/component-documents/openpgp-setup.md @@ -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)"` - - * You may test the variable was set correctly using `echo $smart_card_id` (tapping tab for auto-completion is helpful here) + a. Set variable with card ID + ``` + $ card_id="$(oct list -i | head -1)"` + ``` + b. Test the variable was set correctly + ``` + $ echo $card_id` + ``` -1. Set the smart card to require touch for all operations (defau admin PIN is 12345678): +1. Set the smart card to require touch for all operations - * `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. - - * `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` + You can insert new smartcards and perform the following steps as needed: + + ``` + $ 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 diff --git a/quorum-vault-system/src/component-documents/tamper-evidence-methods.md b/quorum-vault-system/src/component-documents/tamper-evidence-methods.md index ac282a7..7d0ccde 100644 --- a/quorum-vault-system/src/component-documents/tamper-evidence-methods.md +++ b/quorum-vault-system/src/component-documents/tamper-evidence-methods.md @@ -131,16 +131,12 @@ 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 - -1. Compare printed photographs of object to the sealed object - -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. - + a. Retrieve digital/physical photographs of both sides of sealed bundle + + b. Compare all photographs to object for differences + + c. Proceed with unsealing the object if no differences are detected + // ANCHOR_END: vsbwf-procedure-unsealing // ANCHOR_END: vsbwf-procedure @@ -236,4 +232,4 @@ Placing objects into a safe helps improve the security of objects, and introduce * [Purism Liberty phone anti-interdiction](http://web.archive.org/web/20240903104700/https://puri.sm/posts/anti-interdiction-on-the-librem-5-usa/) // ANCHOR_END: entire-doc -/* ANCHOR_END: all */ \ No newline at end of file +/* ANCHOR_END: all */ diff --git a/quorum-vault-system/src/generated-documents/all-levels/pgp-key-provisioning.md b/quorum-vault-system/src/generated-documents/all-levels/pgp-key-provisioning.md index 682120a..6a8d833 100644 --- a/quorum-vault-system/src/generated-documents/all-levels/pgp-key-provisioning.md +++ b/quorum-vault-system/src/generated-documents/all-levels/pgp-key-provisioning.md @@ -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 ` +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 > .asc` - -1. Place the file in `keys/all/.asc` - - * `mv .asc keys/all/` - -1. Stage the modified file: - - * `git add keys/all/.asc` - -1. Create signed git commit: - - * `git commit -S -m "add pgp key"` - -1. Push to the commit: - - * `git push origin main` + a. Clone repository (if not done previously) + ``` + $ git clone ~/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 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 .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 }} \ No newline at end of file + * e.g. `gpg --import .asc` + * Confirm this is done for keyrings on workstations used to interact with the Vaults repository