From 0310feaecc5267215215180305cffba1ecfd7958 Mon Sep 17 00:00:00 2001 From: Phill Kelley <34226495+Paraphraser@users.noreply.github.com> Date: Wed, 28 Jun 2023 23:44:09 +1000 Subject: [PATCH 1/3] 2023-06-28 Add section on setting up multiple hosts Issue #382 suggests adding a section explaining how to use the same YubiKey on multiple hosts. This PR incorporates most of the suggestions. Fixes: #382 Signed-off-by: Phill Kelley <34226495+Paraphraser@users.noreply.github.com> --- README.md | 74 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) diff --git a/README.md b/README.md index cf92f75..31ef283 100644 --- a/README.md +++ b/README.md @@ -48,6 +48,7 @@ If you have a comment or suggestion, please open an [Issue](https://github.com/d - [Verify card](#verify-card) - [Multiple YubiKeys](#multiple-yubikeys) - [Switching between two or more Yubikeys](#switching-between-two-or-more-yubikeys) +- [Multiple Hosts](#multiple-hosts) - [Cleanup](#cleanup) - [Using keys](#using-keys) - [Rotating keys](#rotating-keys) @@ -1676,6 +1677,79 @@ GPG will then scan your first Yubikey for GPG keys and recreate the stubs to poi To return to using the second Yubikey just repeat (insert other Yubikey and re-run command). Obviously this command is not easy to remember so it is recommended to either create a script or a shell alias to make this more user friendly. + +# Multiple Hosts + +It can be convenient to use your YubiKey on multiple hosts: + +* a desktop plus a laptop +* home and work computers +* an environment like [Tails](https://tails.boum.org) + +The simplest way to set up a second host is to begin by exporting your public key and trust settings on the host where your YubiKey is already working: + +``` console +$ gpg --armor --export $KEYID > gpg-public-key-$KEYID.asc +$ gpg --export-ownertrust > gpg-owner-trust.txt +``` + +Move both files to the second host. Then, on the second host: + +1. Define your KEYID. For example: + + ``` console + $ export KEYID=0xFF3E7D88647EBCDB + ``` + +2. Import your public key: + + ``` console + $ gpg --import gpg-public-key-$KEYID.asc + ``` + +3. Import the trust settings: + + ``` console + $ gpg --import-ownertrust < gpg-owner-trust.txt + ``` + +4. Insert your YubiKey into a USB port. +5. Import the private key stubs from the YubiKey: + + ``` console + $ gpg --card-status + ``` + +If you need to set up a second host when you are travelling and don't have ready access to your primary host, you can import your public key from a key-server and set trust manually: + +1. Define your KEYID. For example: + + ``` console + $ export KEYID=0xFF3E7D88647EBCDB + ``` + +2. Fetch the public key from a key-server. For example: + + ``` console + $ gpg --keyserver hkps://keyserver.ubuntu.com:443 --recv $KEYID + ``` + +3. Set ultimate trust: + + ``` console + $ gpg --edit-key $KEYID + gpg> trust + Your decision? 5 + Do you really want to set this key to ultimate trust? (y/N) y + gpg> quit + ``` + +4. Insert your YubiKey into a USB port. +5. Import the private key stubs from the YubiKey: + + ``` console + $ gpg --card-status + ``` # Cleanup From 008f1caf79eb21455ad0f1508251dc5320197f6d Mon Sep 17 00:00:00 2001 From: Phill Kelley <34226495+Paraphraser@users.noreply.github.com> Date: Thu, 29 Jun 2023 11:35:30 +1000 Subject: [PATCH 2/3] explain use of card URL field to obtain public key from keyserver Signed-off-by: Phill Kelley <34226495+Paraphraser@users.noreply.github.com> --- README.md | 69 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 69 insertions(+) diff --git a/README.md b/README.md index 31ef283..d9feffd 100644 --- a/README.md +++ b/README.md @@ -1750,6 +1750,75 @@ If you need to set up a second host when you are travelling and don't have ready ``` console $ gpg --card-status ``` + +Another approach is to add the URL of your public key to your YubiKey: + +1. Define your KEYID. For example: + + ``` console + $ KEYID=0xFF3E7D88647EBCDB + ``` + +2. Construct the URL (based on [Shaw 2003](https://datatracker.ietf.org/doc/html/draft-shaw-openpgp-hkp-00)): + + ``` + $ [[ ! "$KEYID" =~ ^"0x" ]] && KEYID="0x${KEYID}" + $ URL="hkps://keyserver.ubuntu.com:443/pks/lookup?op=get&search=${KEYID}" + $ echo $URL + hkps://keyserver.ubuntu.com:443/pks/lookup?op=get&search=0xFF3E7D88647EBCDB + ``` + +3. Insert your YubiKey into a USB port. +4. Add the URL to your YubiKey (will prompt for your YubiKey's admin PIN): + + ``` + $ gpg --edit-card + gpg/card> admin + gpg/card> url + URL to retrieve public key: hkps://keyserver.ubuntu.com:443/pks/lookup?op=get&search=0xFF3E7D88647EBCDB + gpg/card> quit + ``` + + Note: + + * You do not have to use a *keyserver* URL. You can export your public key as an armored ASCII file and upload it to any place on the web where it can be downloaded using HTTP/HTTPS. + +Once the URL of your public key is present on your YubiKey, setting up a new host becomes: + +1. Insert your YubiKey into a USB port. + +2. Use the `fetch` sub-command to retrieve your public key using the URL stored on the card: + + ``` + $ gpg --edit-card + + gpg/card> fetch + gpg: requesting key from 'hkps://keyserver.ubuntu.com:443/pks/lookup?op=get&search=0xFF3E7D88647EBCDB' + gpg: /home/pi/.gnupg/trustdb.gpg: trustdb created + gpg: key FF3E7D88647EBCDB: public key "Dr Duh " imported + gpg: Total number processed: 1 + gpg: imported: 1 + + gpg/card> quit + ``` + + This step also imports the private key stubs from the YubiKey. + +3. Define your KEYID (which appears in the output in the previous step): + + ``` console + $ export KEYID=0xFF3E7D88647EBCDB + ``` + +4. Set ultimate trust: + + ``` console + $ gpg --edit-key $KEYID + gpg> trust + Your decision? 5 + Do you really want to set this key to ultimate trust? (y/N) y + gpg> quit + ``` # Cleanup From 61def5abdad6d8eb9ba0146bd8003342649f3026 Mon Sep 17 00:00:00 2001 From: Phill Kelley <34226495+Paraphraser@users.noreply.github.com> Date: Thu, 29 Jun 2023 14:24:25 +1000 Subject: [PATCH 3/3] add missing code-fence language indicators + zap extraneous tabs Signed-off-by: Phill Kelley <34226495+Paraphraser@users.noreply.github.com> --- README.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index d9feffd..0e6d088 100644 --- a/README.md +++ b/README.md @@ -1733,7 +1733,7 @@ If you need to set up a second host when you are travelling and don't have ready ``` console $ gpg --keyserver hkps://keyserver.ubuntu.com:443 --recv $KEYID ``` - + 3. Set ultimate trust: ``` console @@ -1761,7 +1761,7 @@ Another approach is to add the URL of your public key to your YubiKey: 2. Construct the URL (based on [Shaw 2003](https://datatracker.ietf.org/doc/html/draft-shaw-openpgp-hkp-00)): - ``` + ``` console $ [[ ! "$KEYID" =~ ^"0x" ]] && KEYID="0x${KEYID}" $ URL="hkps://keyserver.ubuntu.com:443/pks/lookup?op=get&search=${KEYID}" $ echo $URL @@ -1771,16 +1771,16 @@ Another approach is to add the URL of your public key to your YubiKey: 3. Insert your YubiKey into a USB port. 4. Add the URL to your YubiKey (will prompt for your YubiKey's admin PIN): - ``` + ``` console $ gpg --edit-card gpg/card> admin gpg/card> url URL to retrieve public key: hkps://keyserver.ubuntu.com:443/pks/lookup?op=get&search=0xFF3E7D88647EBCDB gpg/card> quit ``` - + Note: - + * You do not have to use a *keyserver* URL. You can export your public key as an armored ASCII file and upload it to any place on the web where it can be downloaded using HTTP/HTTPS. Once the URL of your public key is present on your YubiKey, setting up a new host becomes: @@ -1789,7 +1789,7 @@ Once the URL of your public key is present on your YubiKey, setting up a new hos 2. Use the `fetch` sub-command to retrieve your public key using the URL stored on the card: - ``` + ``` console $ gpg --edit-card gpg/card> fetch @@ -1801,9 +1801,9 @@ Once the URL of your public key is present on your YubiKey, setting up a new hos gpg/card> quit ``` - + This step also imports the private key stubs from the YubiKey. - + 3. Define your KEYID (which appears in the output in the previous step): ``` console @@ -1819,7 +1819,7 @@ Once the URL of your public key is present on your YubiKey, setting up a new hos Do you really want to set this key to ultimate trust? (y/N) y gpg> quit ``` - + # Cleanup Before finishing the setup, ensure you have done the following: