public
/
docs
5
0
Fork 0
Code Issues 9 Pull Requests 3 Packages Projects Releases Wiki Activity
docs/quorum-key-management/src/component-documents/openpgp-setup.md

4.4 KiB
Raw Blame History

/* 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.

Generating Keys using keyfork and openpgp-card-tools

// ANCHOR: steps-keyfork

  1. Generate a mnemonic:

    • keyfork mnemonic generate --size 256 > mnemonic.txt

  2. 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)

  3. 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

    • Burn the piece of paper which has the mnemonic written on it

  4. 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

  5. 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

      • You can come up with your own alpha numeric PIN or 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, $6 }' > 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>

  6. Import PGP key into keyring

    • gpg --import priv.asc

  7. 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]

  8. Rename the private key file to contain the key_id:

    • mv priv.asc key_id.priv

  9. Export the public key:

    • gpg --export --armor <key_id> > <key_id>.pub

  10. Bundle all data and encrypt it

    • mkdir backup_bundle/

    • mv <key_id>.pub <key_id>.priv smart-card-pin.txt backup_bundle/

    • tar -cvf backup_bundle.tar backup_bundle/

    • gpg --armor -er <key_id> backup_bundle.tar

  11. 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

// ANCHOR_END: steps-keyfork

Generating Keys on Smartcard

// ANCHOR: steps-on-key-gen

  1. Insert the smart card into the USB port if it is not already plugged in.

  2. Open Command Prompt (Windows) or Terminal (macOS / Linux).

  3. Enter the GPG command:

    • gpg --card-edit

  4. At the gpg/card> prompt, enter the command: admin

  5. If you want to use keys larger than 2048 bits, run: key-attr

  6. Enter the command: generate

  7. 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 the key.

  8. Specify how long the key should be valid for (specify the number in days, weeks, months, or years).

  9. Confirm the expiration day.

  10. When prompted, enter your name.

  11. Enter your email address.

  12. If needed, enter a comment.

  13. Review the name and email, and accept or make changes.

  14. Enter the default admin PIN again. The green light on the smart card will flash while the keys are being written.

  15. 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

/* ANCHOR_END: all */