From 2c2cec316ce8eb6859ae0bb1470623638a99931b Mon Sep 17 00:00:00 2001 From: drduh Date: Wed, 12 Feb 2020 09:38:36 -0800 Subject: [PATCH 01/44] Bump Debian version, license year --- LICENSE | 2 +- README.md | 40 ++++++++++++++++++++++++++++++++-------- 2 files changed, 33 insertions(+), 9 deletions(-) diff --git a/LICENSE b/LICENSE index a7d93da..e1efebe 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ The MIT License (MIT) -Copyright (c) 2016-2019 drduh +Copyright (c) 2016-2020 drduh Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/README.md b/README.md index 8ddede5..f3ba270 100644 --- a/README.md +++ b/README.md @@ -86,7 +86,7 @@ Depending on your threat model and/or level of inherent trust in your own system To use Debian, download the latest image: ```console -$ curl -LfO https://cdimage.debian.org/debian-cd/current-live/amd64/iso-hybrid/debian-live-10.2.0-amd64-xfce.iso +$ curl -LfO https://cdimage.debian.org/debian-cd/current-live/amd64/iso-hybrid/debian-live-10.3.0-amd64-xfce.iso $ curl -LfO https://cdimage.debian.org/debian-cd/current-live/amd64/iso-hybrid/SHA512SUMS @@ -97,18 +97,17 @@ Verify the signature of the hashes file with GPG: ```console $ gpg --verify SHA512SUMS.sign SHA512SUMS -gpg: Signature made Sat Nov 16 18:49:18 2019 PST +gpg: Signature made Sat Feb 8 18:02:16 2020 PST gpg: using RSA key DF9B9C49EAA9298432589D76DA87E80D6294BE9B gpg: Can't check signature: No public key $ gpg --keyserver hkps://keyring.debian.org --recv DF9B9C49EAA9298432589D76DA87E80D6294BE9B -gpg: key 0xDA87E80D6294BE9B: 5 signatures not checked due to missing keys gpg: key 0xDA87E80D6294BE9B: public key "Debian CD signing key " imported gpg: Total number processed: 1 gpg: imported: 1 $ gpg --verify SHA512SUMS.sign SHA512SUMS -gpg: Signature made Sat Nov 16 18:49:18 2019 PST +gpg: Signature made Sat Feb 8 18:02:16 2020 PST gpg: using RSA key DF9B9C49EAA9298432589D76DA87E80D6294BE9B gpg: Good signature from "Debian CD signing key " [unknown] gpg: WARNING: This key is not certified with a trusted signature! @@ -125,8 +124,8 @@ $ gpg --keyserver hkps://keyserver.ubuntu.com:443 --recv DF9B9C49EAA9298432589D7 Ensure the SHA512 hash of the live image matches the one in the signed file. ```console -$ grep $(sha512sum debian-live-10.2.0-amd64-xfce.iso) SHA512SUMS -SHA512SUMS:b253e347bf04c4e16b4c948b88bfba58f6084717f8ca290d5ea320837f63cf69b46734b7127dabd114ad88022075020982434fcf31463b82c6225671e7116a4d debian-live-10.2.0-amd64-xfce.iso +$ grep $(sha512sum debian-live-10.3.0-amd64-xfce.iso) SHA512SUMS +SHA512SUMS:c6adede144eb32b7316b65342f7445cb13b95ef17551d47ce1a8468d3954710f5f68c979c1086aa1b94262c8bfd86679eb38b01731c7b9aaeaca690455f1ff7f debian-live-10.3.0-amd64-xfce.iso ``` See [Verifying authenticity of Debian CDs](https://www.debian.org/CD/verify) for more information. @@ -148,7 +147,7 @@ sd 2:0:0:0: [sdb] Write cache: disabled, read cache: enabled, doesn't support DP sdb: sdb1 sdb2 sd 2:0:0:0: [sdb] Attached SCSI removable disk -$ sudo dd if=debian-live-10.2.0-amd64-xfce.iso of=/dev/sdb bs=4M; sync +$ sudo dd if=debian-live-10.3.0-amd64-xfce.iso of=/dev/sdb bs=4M; sync 465+1 records in 465+1 records out 1951432704 bytes (2.0 GB, 1.8 GiB) copied, 42.8543 s, 45.5 MB/s @@ -161,7 +160,7 @@ $ dmesg | tail -n2 sd2 at scsibus4 targ 1 lun 0: SCSI4 0/direct removable serial.0000000000000 sd2: 15193MB, 512 bytes/sector, 31116288 sectors -$ doas dd if=debian-live-10.2.0-amd64-xfce.iso of=/dev/rsd2c bs=4m +$ doas dd if=debian-live-10.3.0-amd64-xfce.iso of=/dev/rsd2c bs=4m 465+1 records in 465+1 records out 1951432704 bytes transferred in 139.125 secs (14026448 bytes/sec) @@ -1570,6 +1569,31 @@ Primary key fingerprint: 011C E16B D45B 27A5 5BA8 776D FF3E 7D88 647E BCDB Subkey fingerprint: 07AA 7735 E502 C5EB E09E B8B0 BECF A3C1 AE19 1D15 ``` +Use a [shell function](https://github.com/drduh/config/blob/master/zshrc) to make encrypting files easier: + +``` +secret () { + output=~/"${1}".$(date +%s).enc + gpg --encrypt --armor --output ${output} -r 0x0000 -r 0x0001 -r 0x0002 "${1}" && echo "${1} -> ${output}" +} + +reveal () { + output=$(echo "${1}" | rev | cut -c16- | rev) + gpg --decrypt --output ${output} "${1}" && echo "${1} -> ${output}" +} +``` + +```console +$ secret document.pdf +document.pdf -> document.pdf.1580000000.enc + +$ reveal document.pdf.1580000000.enc +gpg: anonymous recipient; trying secret key 0xFF3E7D88647EBCDB ... +gpg: okay, we are the anonymous recipient. +gpg: encrypted with RSA key, ID 0x0000000000000000 +document.pdf.1580000000.enc -> document.pdf +``` + # Rotating keys PGP does not provide forward secrecy - a compromised key may be used to decrypt all past messages. Although keys stored on YubiKey are difficult to steal, it is not impossible - the key and PIN could be taken, or a vulnerability may be discovered in key hardware or random number generator used to create them, for example. Therefore, it is good practice to occassionally rotate sub-keys. From db1d86cdd82bfffc6628f6538d3ac19d7aa73abe Mon Sep 17 00:00:00 2001 From: Murphy Laptop Date: Mon, 2 Mar 2020 21:18:56 +0100 Subject: [PATCH 02/44] Added some additonal text describing alternatives that may be used --- README.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/README.md b/README.md index f3ba270..05bdf22 100644 --- a/README.md +++ b/README.md @@ -326,6 +326,8 @@ An entropy pool value greater than 2000 is sufficient. # Creating keys +## Using a temporary file system (Tmpfs) + Create a temporary directory which will be cleared on [reboot](https://en.wikipedia.org/wiki/Tmpfs): ```console @@ -334,6 +336,19 @@ $ export GNUPGHOME=$(mktemp -d) $ cd $GNUPGHOME ``` +## Use the Storage Device as backup and reusable enviroment + +As you may want to keep a offline backup of your keys as well as a clean enviroment to be set up easily, you also might consider to keep your USB-Storage device including the keys in a save place. Therefore, just set your desired GNUPGHOME-Variable: + +```console +$ export GNUPGHOME=~/gnupg-workspace + +$ cd $GNUPGHOME +``` +**Remember** You must store the device in a secure place afterwards or destroy it physically (smash, burn, shred etc.) + +## Harden your setup + Create a hardened configuration in the temporary directory with the following options: ```console From b5adb349ad790bbdf34e3d28d9a543b008554f1c Mon Sep 17 00:00:00 2001 From: Daniel Sockwell Date: Tue, 24 Mar 2020 12:42:42 -0400 Subject: [PATCH 03/44] Add steps for renewing (not rotating) sub-keys As discussed in issue #164, the current section on Rotating Keys presents two alternatives: replacing the existing keys with a newly generated key or extending the validity of existing keys by changing their expiration. However, it only provides instructions for the first approach. This commit adds instructions for renewing sub-keys. I am far from an expert, and am submitting this change mostly in hopes that it will provide documentation for the next time I need to renew my sub-keys. I would welcome any changes or clarifications others would care to offer. --- README.md | 103 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 102 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index f3ba270..3895fd6 100644 --- a/README.md +++ b/README.md @@ -1604,6 +1604,8 @@ Replacing keys, on the other hand, is less convenient but more secure: the new s Neither rotation method is superior and it's up to personal philosophy on identity management and individual threat model to decide which one to use, or whether to expire sub-keys at all. Ideally, sub-keys would be ephemeral: used only once for each encryption, signing and authentication event, however in practice that is not really feasible or worthwhile with YubiKey. Advanced users may want to dedicate an offline device for more frequent key rotations and ease of provisioning. +### Initial setup for rotating keys or renewing sub-keys + To renew or rotate sub-keys, follow the same procedure to boot to a secure environment. Install required software and disconnect networking. Decrypt and mount the offline volume, then import the master key and configuration to a temporary working directory: ```console @@ -1625,7 +1627,106 @@ Secret key is available [...] ``` -Follow the original steps to generate each sub-key. Previous sub-keys may be kept or deleted from the identity. +### Renewing sub-keys + +Renewing sub-keys is simpler: you do not need to generate new keys, move keys to the YubiKey, or update any SSH public keys linked to the GPG key. All you need to do is to change the expiry time associated with the public key (which requires access to the master key you just loaded) and then to export that public key and import it on any computer where you wish to use the **GPG** (as distinct from the SSH) key. + +To change the expiration date of all sub-keys, start by selecting all keys: + +```console +$ gpg --edit-key $KEYID + +Secret key is available. + +sec rsa4096/0xFF3E7D88647EBCDB + created: 2017-10-09 expires: never usage: C + trust: ultimate validity: ultimate +ssb rsa4096/0xBECFA3C1AE191D15 + created: 2017-10-09 expires: 2018-10-09 usage: S +ssb rsa4096/0x5912A795E90DD2CF + created: 2017-10-09 expires: 2018-10-09 usage: E +ssb rsa4096/0x3F29127E79649A3D + created: 2017-10-09 expires: 2018-10-09 usage: A +[ultimate] (1). Dr Duh + +gpg> key 1 + +Secret key is available. + +sec rsa4096/0xFF3E7D88647EBCDB + created: 2017-10-09 expires: never usage: C + trust: ultimate validity: ultimate +ssb* rsa4096/0xBECFA3C1AE191D15 + created: 2017-10-09 expires: 2018-10-09 usage: S +ssb rsa4096/0x5912A795E90DD2CF + created: 2017-10-09 expires: 2018-10-09 usage: E +ssb rsa4096/0x3F29127E79649A3D + created: 2017-10-09 expires: 2018-10-09 usage: A +[ultimate] (1). Dr Duh + +gpg> key 2 + +Secret key is available. + +sec rsa4096/0xFF3E7D88647EBCDB + created: 2017-10-09 expires: never usage: C + trust: ultimate validity: ultimate +ssb* rsa4096/0xBECFA3C1AE191D15 + created: 2017-10-09 expires: 2018-10-09 usage: S +ssb* rsa4096/0x5912A795E90DD2CF + created: 2017-10-09 expires: 2018-10-09 usage: E +ssb rsa4096/0x3F29127E79649A3D + created: 2017-10-09 expires: 2018-10-09 usage: A +[ultimate] (1). Dr Duh + +gpg> key 3 + +Secret key is available. + +sec rsa4096/0xFF3E7D88647EBCDB + created: 2017-10-09 expires: never usage: C + trust: ultimate validity: ultimate +ssb* rsa4096/0xBECFA3C1AE191D15 + created: 2017-10-09 expires: 2018-10-09 usage: S +ssb* rsa4096/0x5912A795E90DD2CF + created: 2017-10-09 expires: 2018-10-09 usage: E +ssb* rsa4096/0x3F29127E79649A3D + created: 2017-10-09 expires: 2018-10-09 usage: A +[ultimate] (1). Dr Duh +``` + +Then, use the `expire` command to set a new expiration date. (Despite the name, this will not cause currently valid keys to become expired). + +```console +gpg> expire +Changing expiration time for a subkey. +Please specify how long the key should be valid. + 0 = key does not expire + = key expires in n days + w = key expires in n weeks + m = key expires in n months + y = key expires in n years +Key is valid for? (0) +``` +Follow these prompts to set a new expiration date, then `quit` to save your changes. + +Next, export your public key: + +```console +$ gpg --export $KEYID > pubkey.gpg +``` + +Transfer that public key to the computer from which you use your GPG key, and then import it with: + +```console +$ gpg --import pubkey.gpg +``` + +This will extend the validity of your GPG key and will allow you to use it for SSH authorization. Note that you do _not_ need to update the SSH public key located on remote servers. + +### Rotating keys + +Rotating keys is more a bit more involved. First, follow the original steps to generate each sub-key. Previous sub-keys may be kept or deleted from the identity. Finish by exporting new keys: From 2698cecd4c34a4bc1dec5ca019a0ba8b0ee561fe Mon Sep 17 00:00:00 2001 From: apiraino Date: Tue, 28 Apr 2020 16:19:18 +0200 Subject: [PATCH 04/44] Add instruction to create a revoke certificate --- README.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/README.md b/README.md index 3895fd6..af705c5 100644 --- a/README.md +++ b/README.md @@ -27,6 +27,7 @@ If you have a comment or suggestion, please open an [Issue](https://github.com/d * [Authentication](#authentication) * [Add extra emails](#add-extra-emails) - [Verify](#verify) +- [Create a revoke certificate](#create-a-revoke-certificate) - [Export](#export) - [Backup](#backup) - [Configure Smartcard](#configure-smartcard) @@ -843,6 +844,20 @@ $ gpg -o \path\to\dir\mastersub.gpg --armor --export-secret-keys $KEYID $ gpg -o \path\to\dir\sub.gpg --armor --export-secret-subkeys $KEYID ``` +# Create a revoke certificate + +Although we will backup and store the master key in a safe place, it is best practice to never rule out the possibility of losing it or having the backup fail. Without the master key it will be impossible to renew or rotate subkeys or generate a revoke certificate, our keychain will be basically useless. + +Even worse, we cannot advertise this fact in any way to those that are using our keys. It is therefore safe to assume that at some point in the future this *will* happen and the only thing that will allow us to deprecate our *orphan* keys is a revoke certificate. + +In order to create the revoke certificate: + +``` console +gpg --output revoke.asc --gen-revoke $KEYID +``` + +The newly created `revoke.asc` file should be stored (or printed) in a place that allows us to retrieve it in case our backup strategy fails. + # Backup Once keys are moved to YubiKey, they cannot be moved again! Create an **encrypted** backup of the keyring and consider using a [paper copy](https://www.jabberwocky.com/software/paperkey/) of the keys as an additional backup measure. From 610855864566ee87e06619d8889f8f55235d317c Mon Sep 17 00:00:00 2001 From: Vladyslav Krylasov Date: Tue, 28 Apr 2020 21:28:44 +0100 Subject: [PATCH 05/44] Describe ykman PGP keys reset --- README.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/README.md b/README.md index 3895fd6..c276804 100644 --- a/README.md +++ b/README.md @@ -2241,6 +2241,12 @@ scd apdu 00 44 00 00 /echo Card has been successfully reset. ``` +Or you may do it via `ykman` if installed: + +```console +$ ykman openpgp reset +``` + # Notes 1. YubiKey has two configurations: one invoked with a short press, and the other with a long press. By default, the short-press mode is configured for HID OTP - a brief touch will emit an OTP string starting with `cccccccc`. If you rarely use the OTP mode, you can swap it to the second configuration via the YubiKey Personalization tool. If you *never* use OTP, you can disable it entirely using the [YubiKey Manager](https://developers.yubico.com/yubikey-manager) application (note, this not the similarly named older YubiKey NEO Manager). From 44d76ac5abb3d3f7fefd166f079ed1f7c86f3cd7 Mon Sep 17 00:00:00 2001 From: Vladyslav Krylasov Date: Wed, 29 Apr 2020 00:52:24 +0100 Subject: [PATCH 06/44] Describe card serial number error --- README.md | 43 +++++++++++++++---------------------------- 1 file changed, 15 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index 3895fd6..11994ed 100644 --- a/README.md +++ b/README.md @@ -2117,38 +2117,24 @@ To use a single identity with multiple YubiKeys - or to replace a lost card with $ gpg-connect-agent "scd serialno" "learn --force" /bye ``` -Alternatively, you could manually delete the GnuPG shadowed key - where the card serial number is stored (see [GnuPG #T2291](https://dev.gnupg.org/T2291)). +Alternatively, you could delete via a script the GnuPG shadowed key - where the card serial number is stored (see [GnuPG #T2291](https://dev.gnupg.org/T2291)). -Find the `Keygrip` number of each key: +Put it somewhere in your `$PATH`. E.g.: ```console -$ gpg --with-keygrip -k $KEYID -pub rsa4096/0xFF3E7D88647EBCDB 2017-10-09 [C] - Key fingerprint = 011C E16B D45B 27A5 5BA8 776D FF3E 7D88 647E BCDB - Keygrip = 7A20855980A62C10569DE893157F38A696B1300E -uid [ ultime ] Dr Duh -sub rsa4096/0xBECFA3C1AE191D15 2017-10-09 [S] [expires: 2018-10-09] - Keygrip = 85D44BD52AD45C0852BD15BF41161EE9AE477398 -sub rsa4096/0x5912A795E90DD2CF 2017-10-09 [E] [expires: 2018-10-09] - Keygrip = A0AA3D9F626BDEA3B833F290C7BCA79216C8A996 -sub rsa4096/0x3F29127E79649A3D 2017-10-09 [A] [expires: 2018-10-09] - Keygrip = 7EF25A1115294342F451BC1CDD0FA94395F2D074 -``` - -Delete all the shadow keys using their `Keygrip` number: - -```console -$ cd ~/.gnupg/private-keys-v1.d +$ cat >> ~/.scripts/remove-keygrips.sh < /dev/null +done -$ rm 85D44BD52AD45C0852BD15BF41161EE9AE477398.key \ - A0AA3D9F626BDEA3B833F290C7BCA79216C8A996.key \ - 7EF25A1115294342F451BC1CDD0FA94395F2D074.key -``` - -Insert the new YubiKey and re-generate shadow-keys by checking card status: - -```console -$ gpg --card-status +gpg --card-status +EOF +$ chmod +x ~/.scripts/remove-keygrips.sh +$ remove-keygrips.sh $KEYID ``` See discussion in Issues [#19](https://github.com/drduh/YubiKey-Guide/issues/19) and [#112](https://github.com/drduh/YubiKey-Guide/issues/112) for more information and troubleshooting steps. @@ -2280,6 +2266,7 @@ scd apdu 00 44 00 00 - If it still fails, it may be useful to stop the background `sshd` daemon process service on the server (e.g. using `sudo systemctl stop sshd`) and instead start it in the foreground with extensive debugging output, using `/usr/sbin/sshd -eddd`. Note that the server will not fork and will only process one connection, therefore has to be re-started after every `ssh` test. +- If you receive the error, `Please insert the card with serial number: *` see [management of multiple keys](#multiple-keys). # Links From bf38b94a65c82c5a4dcc317f0884289ff18c94e0 Mon Sep 17 00:00:00 2001 From: drduh Date: Sun, 3 May 2020 13:45:58 -0700 Subject: [PATCH 07/44] Disambiguate backup volume label to fix #176. --- README.md | 204 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 127 insertions(+), 77 deletions(-) diff --git a/README.md b/README.md index 935352d..39cf31d 100644 --- a/README.md +++ b/README.md @@ -6,11 +6,10 @@ Keys stored on YubiKey are [non-exportable](https://support.yubico.com/support/s If you have a comment or suggestion, please open an [Issue](https://github.com/drduh/YubiKey-Guide/issues) on GitHub. -- [Purchase YubiKey](#purchase-yubikey) -- [Verify YubiKey](#verify-yubikey) +- [Purchase](#purchase) - [Download OS Image](#download-os-image) - [Required software](#required-software) - * [Debian/Ubuntu](#debianubuntu) + * [Debian/Ubuntu](#debian-ubuntu) * [Arch](#arch) * [RHEL7](#rhel7) * [NixOS](#nixos) @@ -19,16 +18,18 @@ If you have a comment or suggestion, please open an [Issue](https://github.com/d * [Windows](#windows) - [Entropy](#entropy) - [Creating keys](#creating-keys) + * [Using a temporary file system](#using-a-temporary-file-system) + * [Harden configuration](#harden-configuration) - [Master key](#master-key) -- [Sign with an existing key (optional)](#sign-with-an-existing-key-optional) +- [Sign with an existing key (optional)](#sign-with-an-existing-key--optional-) - [Sub-keys](#sub-keys) * [Signing](#signing) * [Encryption](#encryption) * [Authentication](#authentication) - * [Add extra emails](#add-extra-emails) + * [Add extra emails (optional)](#add-extra-emails--optional-) - [Verify](#verify) -- [Create a revoke certificate](#create-a-revoke-certificate) - [Export](#export) +- [Create a revoke certificate](#create-a-revoke-certificate) - [Backup](#backup) - [Configure Smartcard](#configure-smartcard) * [Change PIN](#change-pin) @@ -38,17 +39,21 @@ If you have a comment or suggestion, please open an [Issue](https://github.com/d * [Encryption](#encryption-1) * [Authentication](#authentication-1) - [Verify card](#verify-card) +- [Multiple keys](#multiple-keys) - [Cleanup](#cleanup) - [Using keys](#using-keys) - [Rotating keys](#rotating-keys) + + [Initial setup for rotating keys or renewing sub-keys](#initial-setup-for-rotating-keys-or-renewing-sub-keys) + + [Renewing sub-keys](#renewing-sub-keys) + + [Rotating keys](#rotating-keys-1) - [SSH](#ssh) * [Create configuration](#create-configuration) * [Replace agents](#replace-agents) * [Copy public key](#copy-public-key) - * [(Optional) Save public key for identity file configuration](#optional-save-public-key-for-identity-file-configuration) + * [(Optional) Save public key for identity file configuration](#-optional--save-public-key-for-identity-file-configuration) * [Connect with public key authentication](#connect-with-public-key-authentication) * [Import SSH keys](#import-ssh-keys) - * [Remote Machines (Agent Forwarding)](#remote-machines-agent-forwarding) + * [Remote Machines (Agent Forwarding)](#remote-machines--agent-forwarding-) + [Steps for older distributions](#steps-for-older-distributions) * [GitHub](#github) * [OpenBSD](#openbsd-1) @@ -66,15 +71,14 @@ If you have a comment or suggestion, please open an [Issue](https://github.com/d - [Troubleshooting](#troubleshooting) - [Links](#links) -# Purchase YubiKey -All YubiKeys except the blue "security key" model are compatible with this guide. NEO models are limited to 2048-bit RSA keys. Compare YubiKeys [here](https://www.yubico.com/products/yubikey-hardware/compare-products-series/). +# Purchase -# Verify YubiKey +All YubiKeys except the blue "security key" model are compatible with this guide. NEO models are limited to 2048-bit RSA keys. Compare YubiKeys [here](https://www.yubico.com/products/yubikey-hardware/compare-products-series/). To verify a YubiKey is genuine, open a [browser with U2F support](https://support.yubico.com/support/solutions/articles/15000009591-how-to-confirm-your-yubico-device-is-genuine-with-u2f) to [https://www.yubico.com/genuine/](https://www.yubico.com/genuine/). Insert a Yubico device, and select *Verify Device* to begin the process. Touch the YubiKey when prompted, and if asked, allow it to see the make and model of the device. If you see *Verification complete*, the device is authentic. -This website verifies the YubiKey's device attestation certificates signed by a set of Yubico CAs, and helps mitigate [supply chain attacks](https://media.defcon.org/DEF%20CON%2025/DEF%20CON%2025%20presentations/DEF%20CON%2025%20-%20r00killah-and-securelyfitz-Secure-Tokin-and-Doobiekeys.pdf). +This website verifies YubiKey device attestation certificates signed by a set of Yubico certificate authorities, and helps mitigate [supply chain attacks](https://media.defcon.org/DEF%20CON%2025/DEF%20CON%2025%20presentations/DEF%20CON%2025%20-%20r00killah-and-securelyfitz-Secure-Tokin-and-Doobiekeys.pdf). # Download OS Image @@ -186,7 +190,21 @@ Open the terminal and install required software packages. ```console $ sudo apt update -$ sudo apt install -y wget gnupg2 gnupg-agent dirmngr cryptsetup scdaemon pcscd secure-delete hopenpgp-tools yubikey-personalization +$ sudo apt -y upgrade + +$ sudo apt -y install wget gnupg2 gnupg-agent dirmngr cryptsetup scdaemon pcscd secure-delete hopenpgp-tools yubikey-personalization +``` + +To install and use the `ykman` utility: + +```console +$ sudo apt -y install python-pip python-pyscard + +$ pip install yubikey-manager + +$ sudo service pcscd start + +$ ~/.local/bin/ykman openpgp info ``` ## Arch @@ -289,7 +307,7 @@ Most operating systems use software-based pseudorandom number generators. A hard Install and configure OneRNG software: ```console -$ sudo apt install -y at rng-tools python-gnupg openssl +$ sudo apt -y install at rng-tools python-gnupg openssl $ wget https://github.com/OneRNG/onerng.github.io/raw/master/sw/onerng_3.6-1_all.deb @@ -327,33 +345,26 @@ An entropy pool value greater than 2000 is sufficient. # Creating keys -## Using a temporary file system (Tmpfs) +## Using a temporary file system -Create a temporary directory which will be cleared on [reboot](https://en.wikipedia.org/wiki/Tmpfs): +Create a temporary directory which will be cleared on [reboot](https://en.wikipedia.org/wiki/Tmpfs) and set it as the GnuPG directory: ```console $ export GNUPGHOME=$(mktemp -d) - -$ cd $GNUPGHOME ``` -## Use the Storage Device as backup and reusable enviroment - -As you may want to keep a offline backup of your keys as well as a clean enviroment to be set up easily, you also might consider to keep your USB-Storage device including the keys in a save place. Therefore, just set your desired GNUPGHOME-Variable: +Otherwise, to preserve the working environment, set the GnuPG directory to your home folder: ```console $ export GNUPGHOME=~/gnupg-workspace - -$ cd $GNUPGHOME ``` -**Remember** You must store the device in a secure place afterwards or destroy it physically (smash, burn, shred etc.) -## Harden your setup +## Harden configuration -Create a hardened configuration in the temporary directory with the following options: +Create a hardened configuration in the temporary working directory with the following options: ```console -$ wget https://raw.githubusercontent.com/drduh/config/master/gpg.conf +$ wget -O $GNUPGHOME/gpg.conf https://raw.githubusercontent.com/drduh/config/master/gpg.conf $ grep -ve "^#" $GNUPGHOME/gpg.conf personal-cipher-preferences AES256 AES192 AES @@ -373,8 +384,8 @@ verify-options show-uid-validity with-fingerprint require-cross-certification no-symkey-cache -throw-keyids use-agent +throw-keyids ``` Disable networking for the remainder of the setup. @@ -387,14 +398,14 @@ The first key to generate is the master key. It will be used for certification o You'll be prompted to enter and verify a passphrase - keep it handy as you'll need it multiple times later. -To generate a strong passphrase which could be written down in a hidden or secure place; or memorized: +Generate a strong passphrase which could be written down in a secure place or memorized: ```console $ gpg --gen-random --armor 0 24 ydOmByxmDe63u7gqx2XI9eDgpvJwibNH ``` -On Linux or OpenBSD, select the password with the mouse to copy it to the clipboard and paste using the middle mouse button or `Shift`-`Insert`. +On Linux or OpenBSD, select the password using the mouse or by double-clicking on it to copy to clipboard. Paste using the middle mouse button or `Shift`-`Insert`. Generate a new key with GPG, selecting `(8) RSA (set your own capabilities)`, `Certify` capability only and `4096` bit key size. @@ -459,7 +470,7 @@ Key does not expire at all Is this correct? (y/N) y ``` -Select a name and email address - neither has to be valid nor existing. +Input any name and email address: ```console GnuPG needs to construct a user ID to identify your key. @@ -717,7 +728,7 @@ Finish by saving the keys. gpg> save ``` -## Add extra emails +## Add extra emails (optional) ```console gpg> adduid @@ -868,10 +879,10 @@ Even worse, we cannot advertise this fact in any way to those that are using our In order to create the revoke certificate: ``` console -gpg --output revoke.asc --gen-revoke $KEYID +$ gpg --gen-revoke $KEYID --output $GNUPGHOME/revoke.asc ``` -The newly created `revoke.asc` file should be stored (or printed) in a place that allows us to retrieve it in case our backup strategy fails. +The `revoke.asc` certificate file should be stored (or printed) in a (secondary) place that allows retrieval in case the main backup fails. # Backup @@ -885,52 +896,61 @@ Attach another external storage device and check its label: ```console $ sudo dmesg | tail -usb-storage 4-2:1.0: USB Mass Storage device detected -scsi host7: usb-storage 4-2:1.0 -scsi 7:0:0:0: Direct-Access TS-RDF5 SD Transcend TS37 PQ: 0 ANSI: 6 -sd 7:0:0:0: Attached scsi generic sg1 type 0 -sd 7:0:0:0: [sdb] 31116288 512-byte logical blocks: (15.9 GB/14.8 GiB) -sd 7:0:0:0: [sdb] Write Protect is off -sd 7:0:0:0: [sdb] Mode Sense: 23 00 00 00 -sdb: sdb1 -sd 7:0:0:0: [sdb] Attached SCSI removable disk +mmc0: new high speed SDHC card at address a001 +mmcblk0: mmc0:a001 SS16G 14.8 GiB + +$ sudo fdisk -l /dev/mmcblk0 +Disk /dev/mmcblk0: 14.9 GiB, 15931539456 bytes, 31116288 sectors +Units: sectors of 1 * 512 = 512 bytes +Sector size (logical/physical): 512 bytes / 512 bytes +I/O size (minimum/optimal): 512 bytes / 512 bytes ``` Write it with random data to prepare for encryption: ```console -$ sudo dd if=/dev/urandom of=/dev/sdb bs=4M status=progress +$ sudo dd if=/dev/urandom of=/dev/mmcblk0 bs=4M status=progress ``` Erase and create a new partition table: ```console -$ sudo fdisk /dev/sdb +$ sudo fdisk /dev/mmcblk0 + Welcome to fdisk (util-linux 2.33.1). +Changes will remain in memory only, until you decide to write them. +Be careful before using the write command. + +Device does not contain a recognized partition table. +Created a new DOS disklabel with disk identifier 0x3c1ad14a. Command (m for help): o -Created a new DOS disklabel with disk identifier 0xeac7ee35. +Created a new DOS disklabel with disk identifier 0xd756b789. Command (m for help): w The partition table has been altered. Calling ioctl() to re-read partition table. Syncing disks. + ``` Create a new partition with a 25 Megabyte size: ```console -$ sudo fdisk /dev/sdb +$ sudo fdisk /dev/mmcblk0 + Welcome to fdisk (util-linux 2.33.1). +Changes will remain in memory only, until you decide to write them. +Be careful before using the write command. Command (m for help): n Partition type p primary (0 primary, 0 extended, 4 free) e extended (container for logical partitions) -Select (default p): +Select (default p): p Partition number (1-4, default 1): -First sector (2048-62980095, default 2048): -Last sector, +sectors or +size{K,M,G,T,P} (2048-62980095, default 62980095): +25M +First sector (2048-31116287, default 2048): +Last sector, +/-sectors or +/-size{K,M,G,T,P} (2048-31116287, default 31116287): +25M Created a new partition 1 of type 'Linux' and of size 25 MiB. @@ -943,29 +963,29 @@ Syncing disks. Use [LUKS](https://askubuntu.com/questions/97196/how-secure-is-an-encrypted-luks-filesystem) to encrypt the new partition: ```console -$ sudo cryptsetup luksFormat /dev/sdb1 +$ sudo cryptsetup luksFormat /dev/mmcblk0p1 WARNING! ======== -This will overwrite data on /dev/sdb1 irrevocably. +This will overwrite data on /dev/mmcblk0p1 irrevocably. Are you sure? (Type uppercase yes): YES -Enter passphrase: +Enter passphrase for /dev/mmcblk0p1: Verify passphrase: ``` Mount the partition: ```console -$ sudo cryptsetup luksOpen /dev/sdb1 usb -Enter passphrase for /dev/sdb1: +$ sudo cryptsetup luksOpen /dev/mmcblk0p1 secret +Enter passphrase for /dev/mmcblk0p1: ``` Create a filesystem: ```console -$ sudo mkfs.ext2 /dev/mapper/usb -L usb -Creating filesystem with 10240 1k blocks and 2560 inodes +$ sudo mkfs.ext2 /dev/mapper/secret -L gpg-$(date +%F) +Creating filesystem with 9216 1k blocks and 2304 inodes Superblock backups stored on blocks: 8193 @@ -977,17 +997,17 @@ Writing superblocks and filesystem accounting information: done Mount the filesystem and copy the temporary directory with the keyring: ```console -$ sudo mkdir /mnt/encrypted-usb +$ sudo mkdir /mnt/encrypted-storage -$ sudo mount /dev/mapper/usb /mnt/encrypted-usb +$ sudo mount /dev/mapper/secret /mnt/encrypted-storage -$ sudo cp -avi $GNUPGHOME /mnt/encrypted-usb +$ sudo cp -avi $GNUPGHOME /mnt/encrypted-storage/ ``` **Optional** Backup the OneRNG package: ```console -$ sudo cp onerng_3.6-1_all.deb /mnt/encrypted-usb +$ sudo cp onerng_3.6-1_all.deb /mnt/encrypted-storage/ ``` Keep the backup mounted if you plan on setting up two or more keys as `keytocard` **will [delete](https://lists.gnupg.org/pipermail/gnupg-users/2016-July/056353.html) the local copy** on save. @@ -995,9 +1015,9 @@ Keep the backup mounted if you plan on setting up two or more keys as `keytocard Unmount, close and disconnected the encrypted volume: ```console -$ sudo umount /mnt/encrypted-usb +$ sudo umount /mnt/encrypted-storage/ -$ sudo cryptsetup luksClose usb +$ sudo cryptsetup luksClose secret ``` Create another partition to store the public key, or skip this step if you plan on uploading it to a key server. @@ -1005,7 +1025,7 @@ Create another partition to store the public key, or skip this step if you plan **Important** Without the *public* key, you will not be able to use GPG to encrypt, decrypt, nor sign messages. However, you will still be able to use YubiKey for SSH authentication. ```console -$ sudo fdisk /dev/sdb +$ sudo fdisk /dev/mmcblk0 Command (m for help): n Partition type @@ -1023,7 +1043,7 @@ The partition table has been altered. Calling ioctl() to re-read partition table. Syncing disks. -$ sudo mkfs.ext2 /dev/sdb2 +$ sudo mkfs.ext2 /dev/mmcblk0p2 Creating filesystem with 10240 1k blocks and 2560 inodes Superblock backups stored on blocks: 8193 @@ -1034,7 +1054,7 @@ Writing superblocks and filesystem accounting information: done $ sudo mkdir /mnt/public -$ sudo mount /dev/sdb2 /mnt/public/ +$ sudo mount /dev/mmcblk0p2 /mnt/public/ $ gpg --armor --export $KEYID | sudo tee /mnt/public/$KEYID-$(date +%F).txt ``` @@ -1299,7 +1319,9 @@ ssb rsa4096/0x3F29127E79649A3D ## Signing -Select and move the signature key. You will be prompted for the key passphrase and Admin PIN. +You will be prompted for the master key passphrase and Admin PIN. + +Select and transfer the signature key. ```console gpg> key 1 @@ -1378,7 +1400,11 @@ gpg> keytocard Please select where to store the key: (3) Authentication key Your selection? 3 +``` + +Save and quit: +```console gpg> save ``` @@ -1398,13 +1424,11 @@ ssb> rsa4096/0x5912A795E90DD2CF 2017-10-09 [E] [expires: 2018-10-09] ssb> rsa4096/0x3F29127E79649A3D 2017-10-09 [A] [expires: 2018-10-09] ``` -# Multiple YubiKeys +# Multiple keys -If you have additional (e.g. backup) security devices, restore the USB backup and repeat the [Configure Smartcard](#configure-smartcard) steps. +To provision additional security keys, restore the master key backup and repeat the [Configure Smartcard](#configure-smartcard) procedure. ```console -$ cd - $ mv -vi $GNUPGHOME $GNUPGHOME.1 renamed '/tmp.FLZC0xcM' -> '/tmp.FLZC0xcM.1' @@ -1418,10 +1442,10 @@ $ cd $GNUPGHOME Ensure you have: -* Saved the encryption, signing and authentication sub-keys to YubiKey. -* Saved the YubiKey PINs which you changed from defaults. -* Saved the password to the master key. -* Saved a copy of the master key, sub-keys and revocation certificates on an encrypted volume, to be stored offline. +* Saved encryption, signing and authentication sub-keys to YubiKey (`gpg -K` should show `ssb>` for sub-keys). +* Saved the YubiKey user and admin PINs which you changed from defaults. +* Saved the password to the GPG master key. +* Saved a copy of the master key, sub-keys and revocation certificate on an encrypted volume, to be stored offline. * Saved the password to that encrypted volume in a separate location. * Saved a copy of the public key somewhere easily accessible later. @@ -1636,7 +1660,25 @@ Neither rotation method is superior and it's up to personal philosophy on identi ### Initial setup for rotating keys or renewing sub-keys -To renew or rotate sub-keys, follow the same procedure to boot to a secure environment. Install required software and disconnect networking. Decrypt and mount the offline volume, then import the master key and configuration to a temporary working directory: +To renew or rotate sub-keys, follow the same process as generating keys: boot to a secure environment, install required software and disconnect networking. + +Connect the offline secret storage device with the master keys and identify the disk label: + +```console +$ sudo dmesg | tail +mmc0: new high speed SDHC card at address a001 +mmcblk0: mmc0:a001 SS16G 14.8 GiB (ro) +mmcblk0: p1 p2 +``` + +Decrypt and mount the offline volume: + +```console +$ sudo cryptsetup luksOpen /dev/mmcblk0p1 secret +Enter passphrase for /dev/mmcblk0p1: +``` + +Import the master key and configuration to a temporary working directory: ```console $ export GNUPGHOME=$(mktemp -d) @@ -2257,10 +2299,16 @@ scd apdu 00 44 00 00 /echo Card has been successfully reset. ``` -Or you may do it via `ykman` if installed: +Or use `ykman`: ```console $ ykman openpgp reset +WARNING! This will delete all stored OpenPGP keys and data and restore factory settings? [y/N]: y +Resetting OpenPGP data, don't remove your YubiKey... +Success! All data has been cleared and default PINs are set. +PIN: 123456 +Reset code: NOT SET +Admin PIN: 12345678 ``` # Notes @@ -2304,6 +2352,8 @@ $ ykman openpgp reset - If you receive the error, `Please insert the card with serial number: *` see [management of multiple keys](#multiple-keys). +- If you receive the error, `There is no assurance this key belongs to the named user` or `encryption failed: Unusable public key` use `gpg --edit-key` to set `trust` to `5 = I trust ultimately`. + # Links * https://alexcabal.com/creating-the-perfect-gpg-keypair/ From 46d1d89115e2d2732617982868a2442f914447c2 Mon Sep 17 00:00:00 2001 From: drduh Date: Sun, 3 May 2020 14:07:35 -0700 Subject: [PATCH 08/44] Split export pubkey from backup to fix #175 --- README.md | 181 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 95 insertions(+), 86 deletions(-) diff --git a/README.md b/README.md index 39cf31d..d30e854 100644 --- a/README.md +++ b/README.md @@ -18,19 +18,20 @@ If you have a comment or suggestion, please open an [Issue](https://github.com/d * [Windows](#windows) - [Entropy](#entropy) - [Creating keys](#creating-keys) - * [Using a temporary file system](#using-a-temporary-file-system) + * [Temporary working directory](#temporary-working-directory) * [Harden configuration](#harden-configuration) - [Master key](#master-key) -- [Sign with an existing key (optional)](#sign-with-an-existing-key--optional-) +- [Sign with existing key](#sign-with-existing-key) - [Sub-keys](#sub-keys) * [Signing](#signing) * [Encryption](#encryption) * [Authentication](#authentication) - * [Add extra emails (optional)](#add-extra-emails--optional-) + * [Add extra identities](#add-extra-identities) - [Verify](#verify) -- [Export](#export) -- [Create a revoke certificate](#create-a-revoke-certificate) +- [Export secret keys](#export-secret-keys) +- [Revocation certificate](#revocation-certificate) - [Backup](#backup) +- [Export public keys](#export-public-keys) - [Configure Smartcard](#configure-smartcard) * [Change PIN](#change-pin) * [Set information](#set-information) @@ -43,9 +44,9 @@ If you have a comment or suggestion, please open an [Issue](https://github.com/d - [Cleanup](#cleanup) - [Using keys](#using-keys) - [Rotating keys](#rotating-keys) - + [Initial setup for rotating keys or renewing sub-keys](#initial-setup-for-rotating-keys-or-renewing-sub-keys) - + [Renewing sub-keys](#renewing-sub-keys) - + [Rotating keys](#rotating-keys-1) + * [Setup environment](#setup-environment) + * [Renewing sub-keys](#renewing-sub-keys) + * [Rotating keys](#rotating-keys-1) - [SSH](#ssh) * [Create configuration](#create-configuration) * [Replace agents](#replace-agents) @@ -345,7 +346,7 @@ An entropy pool value greater than 2000 is sufficient. # Creating keys -## Using a temporary file system +## Temporary working directory Create a temporary directory which will be cleared on [reboot](https://en.wikipedia.org/wiki/Tmpfs) and set it as the GnuPG directory: @@ -505,9 +506,9 @@ Export the key ID as a [variable](https://stackoverflow.com/questions/1158091/de $ export KEYID=0xFF3E7D88647EBCDB ``` -# Sign with an existing key (optional) +# Sign with existing key -If you already have a PGP key, you may want to sign the new key with the old one to prove that the new key is controlled by you. +(Optional) If you already have a PGP key, you may want to sign the new key with the old one to prove that the new key is controlled by you. Export your existing key to move it to the working keyring: @@ -728,7 +729,9 @@ Finish by saving the keys. gpg> save ``` -## Add extra emails (optional) +## Add extra identities + +(Optional) To add additional email addresses or identities, use `adduid`: ```console gpg> adduid @@ -750,7 +753,6 @@ ssb rsa4096/0x3F29127E79649A3D [ultimate] (1). Dr Duh [ unknown] (2). Dr Duh - gpg> trust sec rsa4096/0xFF3E7D88647EBCDB created: 2017-10-09 expires: never usage: SC @@ -820,7 +822,7 @@ ssb rsa4096/0x3F29127E79649A3D gpg> save ``` -By default, the last identity added will be the primary user ID. Use `primary` to change that. +By default, the last identity added will be the primary user ID - use `primary` to change that. # Verify @@ -850,7 +852,7 @@ The output will display any problems with your key in red text. If everything is > hokey may warn (orange text) about cross certification for the authentication key. GPG's [Signing Subkey Cross-Certification](https://gnupg.org/faq/subkey-cross-certify.html) documentation has more detail on cross certification, and gpg v2.2.1 notes "subkey does not sign and so does not need to be cross-certified". hokey may also indicate a problem (red text) with `Key expiration times: []` on the primary key (see [Note #3](#notes) about not setting an expiry for the primary key). -# Export +# Export secret keys The master key and sub-keys will be encrypted with your passphrase when exported. @@ -870,13 +872,13 @@ $ gpg -o \path\to\dir\mastersub.gpg --armor --export-secret-keys $KEYID $ gpg -o \path\to\dir\sub.gpg --armor --export-secret-subkeys $KEYID ``` -# Create a revoke certificate +# Revocation certificate -Although we will backup and store the master key in a safe place, it is best practice to never rule out the possibility of losing it or having the backup fail. Without the master key it will be impossible to renew or rotate subkeys or generate a revoke certificate, our keychain will be basically useless. +Although we will backup and store the master key in a safe place, it is best practice to never rule out the possibility of losing it or having the backup fail. Without the master key, it will be impossible to renew or rotate subkeys or generate a revocation certificate, the PGP identity will be useless. -Even worse, we cannot advertise this fact in any way to those that are using our keys. It is therefore safe to assume that at some point in the future this *will* happen and the only thing that will allow us to deprecate our *orphan* keys is a revoke certificate. +Even worse, we cannot advertise this fact in any way to those that are using our keys. It is reasonable to assume this *will* occur at some point and the only remaining way to deprecate orphaned keys is a revocation certificate. -In order to create the revoke certificate: +To create the revocation certificate: ``` console $ gpg --gen-revoke $KEYID --output $GNUPGHOME/revoke.asc @@ -1020,64 +1022,6 @@ $ sudo umount /mnt/encrypted-storage/ $ sudo cryptsetup luksClose secret ``` -Create another partition to store the public key, or skip this step if you plan on uploading it to a key server. - -**Important** Without the *public* key, you will not be able to use GPG to encrypt, decrypt, nor sign messages. However, you will still be able to use YubiKey for SSH authentication. - -```console -$ sudo fdisk /dev/mmcblk0 - -Command (m for help): n -Partition type - p primary (1 primary, 0 extended, 3 free) - e extended (container for logical partitions) -Select (default p): -Partition number (2-4, default 2): -First sector (22528-31116287, default 22528): -Last sector, +sectors or +size{K,M,G,T,P} (22528-31116287, default 31116287): +25M - -Created a new partition 2 of type 'Linux' and of size 25 MiB. - -Command (m for help): w -The partition table has been altered. -Calling ioctl() to re-read partition table. -Syncing disks. - -$ sudo mkfs.ext2 /dev/mmcblk0p2 -Creating filesystem with 10240 1k blocks and 2560 inodes -Superblock backups stored on blocks: - 8193 - -Allocating group tables: done -Writing inode tables: done -Writing superblocks and filesystem accounting information: done - -$ sudo mkdir /mnt/public - -$ sudo mount /dev/mmcblk0p2 /mnt/public/ - -$ gpg --armor --export $KEYID | sudo tee /mnt/public/$KEYID-$(date +%F).txt -``` - -Windows: - -```console -$ gpg -o \path\to\dir\pubkey.gpg --armor --export $KEYID -``` - -**Optional** Upload the public key to a [public keyserver](https://debian-administration.org/article/451/Submitting_your_GPG_key_to_a_keyserver): - -```console -$ gpg --send-key $KEYID - -$ gpg --keyserver pgp.mit.edu --send-key $KEYID - -$ gpg --keyserver keys.gnupg.net --send-key $KEYID - -$ gpg --keyserver hkps://keyserver.ubuntu.com:443 --send-key $KEYID -``` - -After some time, the public key will to propagate to [other](https://pgp.key-server.io/pks/lookup?search=doc%40duh.to&fingerprint=on&op=vindex) [servers](https://pgp.mit.edu/pks/lookup?search=doc%40duh.to&op=index). **OpenBSD** @@ -1161,9 +1105,50 @@ $ doas bioctl -d sd3 See [OpenBSD FAQ#14](https://www.openbsd.org/faq/faq14.html#softraidCrypto) for more information. -Create another partition to store the public key, or skip this step if you plan on uploading it to a key server. +# Export public keys + +**Important** Without the *public* key, you will not be able to use GPG to encrypt, decrypt, nor sign messages. However, you will still be able to use YubiKey for SSH authentication. + +Create another partition on the removable storage device to store the public key, or reconnect networking and upload to a key server. + +**Linux** + +```console +$ sudo fdisk /dev/mmcblk0 + +Command (m for help): n +Partition type + p primary (1 primary, 0 extended, 3 free) + e extended (container for logical partitions) +Select (default p): +Partition number (2-4, default 2): +First sector (22528-31116287, default 22528): +Last sector, +sectors or +size{K,M,G,T,P} (22528-31116287, default 31116287): +25M -**Important** Without the public key, you will not be able to use GPG to encrypt, decrypt, nor sign messages. However, you will still be able to use YubiKey for SSH authentication. +Created a new partition 2 of type 'Linux' and of size 25 MiB. + +Command (m for help): w +The partition table has been altered. +Calling ioctl() to re-read partition table. +Syncing disks. + +$ sudo mkfs.ext2 /dev/mmcblk0p2 +Creating filesystem with 10240 1k blocks and 2560 inodes +Superblock backups stored on blocks: + 8193 + +Allocating group tables: done +Writing inode tables: done +Writing superblocks and filesystem accounting information: done + +$ sudo mkdir /mnt/public + +$ sudo mount /dev/mmcblk0p2 /mnt/public/ + +$ gpg --armor --export $KEYID | sudo tee /mnt/public/$KEYID-$(date +%F).txt +``` + +**OpenBSD** ```console $ doas disklabel -E sd2 @@ -1185,9 +1170,29 @@ $ doas mount /dev/sd2b /mnt/public $ gpg --armor --export $KEYID | doas tee /mnt/public/$KEYID.txt ``` -# Configure Smartcard +**Windows** + +```console +$ gpg -o \path\to\dir\pubkey.gpg --armor --export $KEYID +``` + +**Keyserver** + +(Optional) Upload the public key to a [public keyserver](https://debian-administration.org/article/451/Submitting_your_GPG_key_to_a_keyserver): + +```console +$ gpg --send-key $KEYID + +$ gpg --keyserver pgp.mit.edu --send-key $KEYID -**Windows** Use the [YubiKey Manager](https://developers.yubico.com/yubikey-manager) application (note, this not the similarly named older YubiKey NEO Manager) to enable CCID functionality. +$ gpg --keyserver keys.gnupg.net --send-key $KEYID + +$ gpg --keyserver hkps://keyserver.ubuntu.com:443 --send-key $KEYID +``` + +After some time, the public key will to propagate to [other](https://pgp.key-server.io/pks/lookup?search=doc%40duh.to&fingerprint=on&op=vindex) [servers](https://pgp.mit.edu/pks/lookup?search=doc%40duh.to&op=index). + +# Configure Smartcard Use GPG to configure YubiKey as a smartcard: @@ -1214,6 +1219,10 @@ Authentication key: [none] General key info..: [none] ``` +**Windows** + +Use the [YubiKey Manager](https://developers.yubico.com/yubikey-manager) application (note, this not the similarly named older YubiKey NEO Manager) to enable CCID functionality. + ## Change PIN The default PIN is `123456` and default Admin PIN (PUK) is `12345678`. CCID-mode PINs can be up to 127 ASCII characters. @@ -1476,7 +1485,7 @@ Install the required packages and mount the non-encrypted volume created earlier ```console $ sudo apt update && sudo apt install -y gnupg2 gnupg-agent gnupg-curl scdaemon pcscd -$ sudo mount /dev/sdb2 /mnt +$ sudo mount /dev/mmcblk0p2 /mnt ``` **OpenBSD** @@ -1658,7 +1667,7 @@ Replacing keys, on the other hand, is less convenient but more secure: the new s Neither rotation method is superior and it's up to personal philosophy on identity management and individual threat model to decide which one to use, or whether to expire sub-keys at all. Ideally, sub-keys would be ephemeral: used only once for each encryption, signing and authentication event, however in practice that is not really feasible or worthwhile with YubiKey. Advanced users may want to dedicate an offline device for more frequent key rotations and ease of provisioning. -### Initial setup for rotating keys or renewing sub-keys +## Setup environment To renew or rotate sub-keys, follow the same process as generating keys: boot to a secure environment, install required software and disconnect networking. @@ -1699,7 +1708,7 @@ Secret key is available [...] ``` -### Renewing sub-keys +## Renewing sub-keys Renewing sub-keys is simpler: you do not need to generate new keys, move keys to the YubiKey, or update any SSH public keys linked to the GPG key. All you need to do is to change the expiry time associated with the public key (which requires access to the master key you just loaded) and then to export that public key and import it on any computer where you wish to use the **GPG** (as distinct from the SSH) key. @@ -1796,7 +1805,7 @@ $ gpg --import pubkey.gpg This will extend the validity of your GPG key and will allow you to use it for SSH authorization. Note that you do _not_ need to update the SSH public key located on remote servers. -### Rotating keys +## Rotating keys Rotating keys is more a bit more involved. First, follow the original steps to generate each sub-key. Previous sub-keys may be kept or deleted from the identity. @@ -1834,7 +1843,7 @@ Export the updated public key: ```console $ sudo mkdir /mnt/public -$ sudo mount /dev/sdb2 /mnt/public +$ sudo mount /dev/mmcblk0p2 /mnt/public $ gpg --armor --export $KEYID | sudo tee /mnt/public/$KEYID-$(date +%F).txt From 93cbbd9d8be0fbb3fac10ab40f2daa9fe9958dbc Mon Sep 17 00:00:00 2001 From: drduh Date: Sun, 3 May 2020 14:18:29 -0700 Subject: [PATCH 09/44] Address throw-keyids issue with mailvelope to fix #178 --- README.md | 32 ++++++++++++++++++-------------- 1 file changed, 18 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index d30e854..53b7c91 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ If you have a comment or suggestion, please open an [Issue](https://github.com/d - [Purchase](#purchase) - [Download OS Image](#download-os-image) - [Required software](#required-software) - * [Debian/Ubuntu](#debian-ubuntu) + * [Debian and Ubuntu](#debian-and-ubuntu) * [Arch](#arch) * [RHEL7](#rhel7) * [NixOS](#nixos) @@ -184,7 +184,7 @@ Boot the live image and configure networking. Open the terminal and install required software packages. -## Debian/Ubuntu +## Debian and Ubuntu **Note** Live Ubuntu images [may require modification](https://github.com/drduh/YubiKey-Guide/issues/116) to `/etc/apt/sources.list` @@ -1086,11 +1086,11 @@ $ doas newfs sd3i Mount the filesystem and copy the temporary directory with the keyring: ```console -$ doas mkdir /mnt/encrypted-usb +$ doas mkdir /mnt/encrypted-storage -$ doas mount /dev/sd3i /mnt/encrypted-usb +$ doas mount /dev/sd3i /mnt/encrypted-storage -$ doas cp -avi $GNUPGHOME /mnt/encrypted-usb +$ doas cp -avi $GNUPGHOME /mnt/encrypted-storage ``` Keep the backup mounted if you plan on setting up two or more keys as `keytocard` **will [delete](https://lists.gnupg.org/pipermail/gnupg-users/2016-July/056353.html) the local copy** on save. @@ -1098,7 +1098,7 @@ Keep the backup mounted if you plan on setting up two or more keys as `keytocard Otherwise, unmount and disconnected the encrypted volume: ```console -$ doas umount /mnt/encrypted-usb +$ doas umount /mnt/encrypted-storage $ doas bioctl -d sd3 ``` @@ -1441,8 +1441,8 @@ To provision additional security keys, restore the master key backup and repeat $ mv -vi $GNUPGHOME $GNUPGHOME.1 renamed '/tmp.FLZC0xcM' -> '/tmp.FLZC0xcM.1' -$ cp -avi /mnt/encrypted-usb/tmp.XXX $GNUPGHOME -'/mnt/encrypted-usb/tmp.FLZC0xcM' -> '/tmp.FLZC0xcM' +$ cp -avi /mnt/encrypted-storage/tmp.XXX $GNUPGHOME +'/mnt/encrypted-storage/tmp.FLZC0xcM' -> '/tmp.FLZC0xcM' $ cd $GNUPGHOME ``` @@ -1685,6 +1685,8 @@ Decrypt and mount the offline volume: ```console $ sudo cryptsetup luksOpen /dev/mmcblk0p1 secret Enter passphrase for /dev/mmcblk0p1: + +$ sudo mount /dev/mapper/secret /mnt/encrypted-storage ``` Import the master key and configuration to a temporary working directory: @@ -1692,9 +1694,9 @@ Import the master key and configuration to a temporary working directory: ```console $ export GNUPGHOME=$(mktemp -d) -$ gpg --import /mnt/encrypted-usb/tmp.XXX/mastersub.key +$ gpg --import /mnt/encrypted-storage/tmp.XXX/mastersub.key -$ cp -v /mnt/encrypted-usb/tmp.XXX/gpg.conf $GNUPGHOME +$ cp -v /mnt/encrypted-storage/tmp.XXX/gpg.conf $GNUPGHOME ``` Edit the master key: @@ -1820,22 +1822,22 @@ $ gpg --armor --export-secret-subkeys $KEYID > $GNUPGHOME/sub.key Copy the **new** temporary working directory to encrypted offline storage, which should still be mounted: ```console -$ sudo cp -avi $GNUPGHOME /mnt/encrypted-usb +$ sudo cp -avi $GNUPGHOME /mnt/encrypted-storage ``` There should now be at least two versions of the master and sub-keys backed up: ```console -$ ls /mnt/encrypted-usb +$ ls /mnt/encrypted-storage lost+found tmp.ykhTOGjR36 tmp.2gyGnyCiHs ``` Unmount and close the encrypted volume: ```console -$ sudo umount /mnt/encrypted-usb +$ sudo umount /mnt/encrypted-storage -$ sudo cryptsetup luksClose /dev/mapper/usb/ +$ sudo cryptsetup luksClose /dev/mapper/secret ``` Export the updated public key: @@ -2258,6 +2260,8 @@ GPG keys on YubiKey can be used with ease to encrypt and/or sign emails and atta [Mailvelope](https://www.mailvelope.com/en) allows GPG keys on YubiKey to be used with Gmail and others. +**Important** Mailvelope [does not work](https://github.com/drduh/YubiKey-Guide/issues/178) with the `throw-keyids` option set in `gpg.conf`. + On macOS, install gpgme using Homebrew: ```console From 07134a4e4f3e532cd8783714049bcabe21b6bdbd Mon Sep 17 00:00:00 2001 From: Jason Stelzer Date: Mon, 4 May 2020 08:22:14 -0400 Subject: [PATCH 10/44] GPG keys on multiple computers I feel like this took me longer to figure out than it should have. --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 53b7c91..129d397 100644 --- a/README.md +++ b/README.md @@ -2330,6 +2330,7 @@ Admin PIN: 12345678 1. Programming YubiKey for GPG keys still lets you use its other configurations - [U2F](https://en.wikipedia.org/wiki/Universal_2nd_Factor), [OTP](https://www.yubico.com/faq/what-is-a-one-time-password-otp/) and [static password](https://www.yubico.com/products/services-software/personalization-tools/static-password/) modes, for example. 1. Setting an expiry essentially forces you to manage your subkeys and announces to the rest of the world that you are doing so. Setting an expiry on a primary key is ineffective for protecting the key from loss - whoever has the primary key can simply extend its expiry period. Revocation certificates are [better suited](https://security.stackexchange.com/questions/14718/does-openpgp-key-expiration-add-to-security/79386#79386) for this purpose. It may be appropriate for your use case to set expiry dates on subkeys. 1. To switch between two or more identities on different keys - unplug the first key and restart gpg-agent, ssh-agent and pinentry with `pkill gpg-agent ; pkill ssh-agent ; pkill pinentry ; eval $(gpg-agent --daemon --enable-ssh-support)`, then plug in the other key and run `gpg-connect-agent updatestartuptty /bye` - then it should be ready for use. +1. To use yubikeys on more than one computer with gpg: After the initial setup, import the public keys on the second workstation. Confirm gpg can see the card via `gpg --card-status`, Trust them ultimately (as above). At this point `gpg --list-secret-keys` should show your (trusted) key. # Troubleshooting From aea317b5276f12c62c5f62a68e9aa082b3b14e8d Mon Sep 17 00:00:00 2001 From: Jason Stelzer Date: Mon, 4 May 2020 08:28:23 -0400 Subject: [PATCH 11/44] Clarified wording --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 129d397..352b46b 100644 --- a/README.md +++ b/README.md @@ -2330,7 +2330,7 @@ Admin PIN: 12345678 1. Programming YubiKey for GPG keys still lets you use its other configurations - [U2F](https://en.wikipedia.org/wiki/Universal_2nd_Factor), [OTP](https://www.yubico.com/faq/what-is-a-one-time-password-otp/) and [static password](https://www.yubico.com/products/services-software/personalization-tools/static-password/) modes, for example. 1. Setting an expiry essentially forces you to manage your subkeys and announces to the rest of the world that you are doing so. Setting an expiry on a primary key is ineffective for protecting the key from loss - whoever has the primary key can simply extend its expiry period. Revocation certificates are [better suited](https://security.stackexchange.com/questions/14718/does-openpgp-key-expiration-add-to-security/79386#79386) for this purpose. It may be appropriate for your use case to set expiry dates on subkeys. 1. To switch between two or more identities on different keys - unplug the first key and restart gpg-agent, ssh-agent and pinentry with `pkill gpg-agent ; pkill ssh-agent ; pkill pinentry ; eval $(gpg-agent --daemon --enable-ssh-support)`, then plug in the other key and run `gpg-connect-agent updatestartuptty /bye` - then it should be ready for use. -1. To use yubikeys on more than one computer with gpg: After the initial setup, import the public keys on the second workstation. Confirm gpg can see the card via `gpg --card-status`, Trust them ultimately (as above). At this point `gpg --list-secret-keys` should show your (trusted) key. +1. To use yubikeys on more than one computer with gpg: After the initial setup, import the public keys on the second workstation. Confirm gpg can see the card via `gpg --card-status`, Trust the public keys you imported ultimately (as above). At this point `gpg --list-secret-keys` should show your (trusted) key. # Troubleshooting From 4c1d538c600b71636aeb9e67e84626965f6ab7c0 Mon Sep 17 00:00:00 2001 From: Vladyslav Krylasov Date: Mon, 4 May 2020 19:19:02 +0100 Subject: [PATCH 12/44] Fix broken anchor There are two anchors with the same name and this breaks navigation. --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 352b46b..44e5e5f 100644 --- a/README.md +++ b/README.md @@ -40,7 +40,7 @@ If you have a comment or suggestion, please open an [Issue](https://github.com/d * [Encryption](#encryption-1) * [Authentication](#authentication-1) - [Verify card](#verify-card) -- [Multiple keys](#multiple-keys) +- [Multiple YubiKeys](#multiple-yubikeys) - [Cleanup](#cleanup) - [Using keys](#using-keys) - [Rotating keys](#rotating-keys) @@ -63,7 +63,7 @@ If you have a comment or suggestion, please open an [Issue](https://github.com/d - [Prerequisites](#prerequisites) - [WSL configuration](#wsl-configuration) - [Remote host configuration](#remote-host-configuration) -- [Multiple Keys](#multiple-keys) +- [Using Multiple Keys](#using-multiple-keys) - [Require touch](#require-touch) - [Email](#email) * [Mailvelope on macOS](#mailvelope-on-macos) @@ -1433,7 +1433,7 @@ ssb> rsa4096/0x5912A795E90DD2CF 2017-10-09 [E] [expires: 2018-10-09] ssb> rsa4096/0x3F29127E79649A3D 2017-10-09 [A] [expires: 2018-10-09] ``` -# Multiple keys +# Multiple YubiKeys To provision additional security keys, restore the master key backup and repeat the [Configure Smartcard](#configure-smartcard) procedure. @@ -2192,7 +2192,7 @@ On the remote host, type `ssh-add -l` - if you see the ssh key, that means forwa **Note** Agent forwarding may be chained through multiple hosts - just follow the same [protocol](#remote-host-configuration) to configure each host. -# Multiple Keys +# Using Multiple Keys To use a single identity with multiple YubiKeys - or to replace a lost card with another - issue this command to switch keys: @@ -2364,7 +2364,7 @@ Admin PIN: 12345678 - If it still fails, it may be useful to stop the background `sshd` daemon process service on the server (e.g. using `sudo systemctl stop sshd`) and instead start it in the foreground with extensive debugging output, using `/usr/sbin/sshd -eddd`. Note that the server will not fork and will only process one connection, therefore has to be re-started after every `ssh` test. -- If you receive the error, `Please insert the card with serial number: *` see [management of multiple keys](#multiple-keys). +- If you receive the error, `Please insert the card with serial number: *` see [using of multiple keys](#using-multiple-keys). - If you receive the error, `There is no assurance this key belongs to the named user` or `encryption failed: Unusable public key` use `gpg --edit-key` to set `trust` to `5 = I trust ultimately`. From de13c8dba6d5c4f6abd57f36b75a586f8e8c49e2 Mon Sep 17 00:00:00 2001 From: Mike Mazur Date: Sun, 17 May 2020 21:00:03 +0800 Subject: [PATCH 13/44] Include --expert when editing master key This is specifically during setup when rotating keys. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 352b46b..e60cb39 100644 --- a/README.md +++ b/README.md @@ -1704,7 +1704,7 @@ Edit the master key: ```console $ export KEYID=0xFF3E7D88647EBCDB -$ gpg --edit-key $KEYID +$ gpg --expert --edit-key $KEYID Secret key is available [...] From 1cf9656b3343596f0d1a1e97d2942e9d285e2171 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Max=20M=C3=A4usezahl?= Date: Sun, 24 May 2020 17:53:56 +0200 Subject: [PATCH 14/44] Fix order of revocation command. According to 'man gpg' the order of arguments should be gpg [--homedir name] [--options file] [options] command [args] In this case '--gen-revoke' is the command, '$KEYID' is an argument and '--output $GNUPGHOME/revoke.asc' is an option. Previously this was incorrect (option came first) and would spawn an error. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index e60cb39..5d4d55b 100644 --- a/README.md +++ b/README.md @@ -881,7 +881,7 @@ Even worse, we cannot advertise this fact in any way to those that are using our To create the revocation certificate: ``` console -$ gpg --gen-revoke $KEYID --output $GNUPGHOME/revoke.asc +$ gpg --output $GNUPGHOME/revoke.asc --gen-revoke $KEYID ``` The `revoke.asc` certificate file should be stored (or printed) in a (secondary) place that allows retrieval in case the main backup fails. From ccb8b0130a4f5a705901d8f4bef3f68505329df9 Mon Sep 17 00:00:00 2001 From: drduh Date: Mon, 25 May 2020 12:49:07 -0700 Subject: [PATCH 15/44] Stack rank secure environment and add a few tips --- README.md | 61 ++++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 42 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index ba675cf..7547788 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ Keys stored on YubiKey are [non-exportable](https://support.yubico.com/support/s If you have a comment or suggestion, please open an [Issue](https://github.com/drduh/YubiKey-Guide/issues) on GitHub. - [Purchase](#purchase) -- [Download OS Image](#download-os-image) +- [Prepare environment](#prepare-environment) - [Required software](#required-software) * [Debian and Ubuntu](#debian-and-ubuntu) * [Arch](#arch) @@ -81,18 +81,26 @@ To verify a YubiKey is genuine, open a [browser with U2F support](https://suppor This website verifies YubiKey device attestation certificates signed by a set of Yubico certificate authorities, and helps mitigate [supply chain attacks](https://media.defcon.org/DEF%20CON%2025/DEF%20CON%2025%20presentations/DEF%20CON%2025%20-%20r00killah-and-securelyfitz-Secure-Tokin-and-Doobiekeys.pdf). -# Download OS Image +You will also need several small storage devices (microSD cards work well) for storing encrypted backups of your keys. -You will need several small storage devices for booting a temporary operating system and creating backups of your private/public keys. +# Prepare environment -It is recommended to generate cryptographic keys and configure YubiKey from a secure operating system and using an ephemeral environment ("live image"), such as [Debian](https://www.debian.org/CD/live/), [Tails](https://tails.boum.org/index.en.html), or [OpenBSD](https://www.openbsd.org/) booted from a USB drive. +To create cryptographic keys, a secure environment that can be reasonably assured to be free of adversarial control is recommended. Here is a general ranking of environments most to least likely to be compromised: -Depending on your threat model and/or level of inherent trust in your own system, it may also be a valid option to run the live image within a virtual machine using [virt-manager](https://virt-manager.org/), VirtualBox, or VMWare software. +1. Daily-use operating system +1. Virtual machine on daily-use host OS (using [virt-manager](https://virt-manager.org/), VirtualBox, or VMWare) +1. Separate hardened [Debian](https://www.debian.org/) or [OpenBSD](https://www.openbsd.org/) installation which can be dual booted +1. Live image, such as [Debian Live](https://www.debian.org/CD/live/) or [Tails](https://tails.boum.org/index.en.html) +1. Secure hardware/firmware ([Coreboot](https://www.coreboot.org/), [Intel ME removed](https://github.com/corna/me_cleaner)) -To use Debian, download the latest image: +1. Dedicated air-gapped system with no networking capabilities + +This guide recommends using a bootable "live" Debian Linux image to provide such an environment, however, depending on your threat model, you may want to take fewer or more steps to secure it. + +To use Debian Live, download the latest image: ```console -$ curl -LfO https://cdimage.debian.org/debian-cd/current-live/amd64/iso-hybrid/debian-live-10.3.0-amd64-xfce.iso +$ curl -LfO https://cdimage.debian.org/debian-cd/current-live/amd64/iso-hybrid/debian-live-10.4.0-amd64-xfce.iso $ curl -LfO https://cdimage.debian.org/debian-cd/current-live/amd64/iso-hybrid/SHA512SUMS @@ -103,7 +111,7 @@ Verify the signature of the hashes file with GPG: ```console $ gpg --verify SHA512SUMS.sign SHA512SUMS -gpg: Signature made Sat Feb 8 18:02:16 2020 PST +gpg: Signature made Sat 09 May 2020 05:17:57 PM PDT gpg: using RSA key DF9B9C49EAA9298432589D76DA87E80D6294BE9B gpg: Can't check signature: No public key @@ -113,7 +121,7 @@ gpg: Total number processed: 1 gpg: imported: 1 $ gpg --verify SHA512SUMS.sign SHA512SUMS -gpg: Signature made Sat Feb 8 18:02:16 2020 PST +gpg: Signature made Sat 09 May 2020 05:17:57 PM PDT gpg: using RSA key DF9B9C49EAA9298432589D76DA87E80D6294BE9B gpg: Good signature from "Debian CD signing key " [unknown] gpg: WARNING: This key is not certified with a trusted signature! @@ -130,8 +138,8 @@ $ gpg --keyserver hkps://keyserver.ubuntu.com:443 --recv DF9B9C49EAA9298432589D7 Ensure the SHA512 hash of the live image matches the one in the signed file. ```console -$ grep $(sha512sum debian-live-10.3.0-amd64-xfce.iso) SHA512SUMS -SHA512SUMS:c6adede144eb32b7316b65342f7445cb13b95ef17551d47ce1a8468d3954710f5f68c979c1086aa1b94262c8bfd86679eb38b01731c7b9aaeaca690455f1ff7f debian-live-10.3.0-amd64-xfce.iso +$ grep $(sha512sum debian-live-10.4.0-amd64-xfce.iso) SHA512SUMS +SHA512SUMS:2920f398c5e9036fcec8f71b2f28b0f2a85e3ab805e66088192dc56f679e5f59f26634e8bbde70badc3cf7ce353f54a2757b2017cbc3d3df9fb2b2065b3c1041 debian-live-10.4.0-amd64-xfce.iso ``` See [Verifying authenticity of Debian CDs](https://www.debian.org/CD/verify) for more information. @@ -153,7 +161,7 @@ sd 2:0:0:0: [sdb] Write cache: disabled, read cache: enabled, doesn't support DP sdb: sdb1 sdb2 sd 2:0:0:0: [sdb] Attached SCSI removable disk -$ sudo dd if=debian-live-10.3.0-amd64-xfce.iso of=/dev/sdb bs=4M; sync +$ sudo dd if=debian-live-10.4.0-amd64-xfce.iso of=/dev/sdb bs=4M; sync 465+1 records in 465+1 records out 1951432704 bytes (2.0 GB, 1.8 GiB) copied, 42.8543 s, 45.5 MB/s @@ -166,7 +174,7 @@ $ dmesg | tail -n2 sd2 at scsibus4 targ 1 lun 0: SCSI4 0/direct removable serial.0000000000000 sd2: 15193MB, 512 bytes/sector, 31116288 sectors -$ doas dd if=debian-live-10.3.0-amd64-xfce.iso of=/dev/rsd2c bs=4m +$ doas dd if=debian-live-10.4.0-amd64-xfce.iso of=/dev/rsd2c bs=4m 465+1 records in 465+1 records out 1951432704 bytes transferred in 139.125 secs (14026448 bytes/sec) @@ -174,8 +182,6 @@ $ doas dd if=debian-live-10.3.0-amd64-xfce.iso of=/dev/rsd2c bs=4m Shut down the computer and disconnect internal hard drives and all unnecessary peripheral devices. If being run within a VM, this part can be skipped as no such devices should be attached to the VM since the image will still be run as a "live image". -If on physical hardware consider using secure hardware like a ThinkPad X230 running [Coreboot](https://www.coreboot.org/) and [cleaned of Intel ME](https://github.com/corna/me_cleaner). - # Required software Boot the live image and configure networking. @@ -196,6 +202,12 @@ $ sudo apt -y upgrade $ sudo apt -y install wget gnupg2 gnupg-agent dirmngr cryptsetup scdaemon pcscd secure-delete hopenpgp-tools yubikey-personalization ``` +To download a copy of this guide: + +```console +$ wget https://raw.githubusercontent.com/drduh/YubiKey-Guide/master/README.md +``` + To install and use the `ykman` utility: ```console @@ -406,6 +418,13 @@ $ gpg --gen-random --armor 0 24 ydOmByxmDe63u7gqx2XI9eDgpvJwibNH ``` +Use upper case letters for improved readability if they are written down: + +```console +$ tr -dc '[:upper:]' < /dev/urandom | fold -w 20 | head -n1 +BSSYMUGGTJQVWZZWOPJG +``` + On Linux or OpenBSD, select the password using the mouse or by double-clicking on it to copy to clipboard. Paste using the middle mouse button or `Shift`-`Insert`. Generate a new key with GPG, selecting `(8) RSA (set your own capabilities)`, `Certify` capability only and `4096` bit key size. @@ -543,7 +562,7 @@ Use a 1 year expiration for sub-keys - they can be renewed using the offline mas ## Signing -Create a [signing key](https://stackoverflow.com/questions/5421107/can-rsa-be-both-used-as-encryption-and-signature/5432623#5432623) by selecting `(4) RSA (sign only)`: +Create a [signing key](https://stackoverflow.com/questions/5421107/can-rsa-be-both-used-as-encryption-and-signature/5432623#5432623) by selecting `addkey` then `(4) RSA (sign only)`: ```console gpg> addkey @@ -1145,7 +1164,7 @@ $ sudo mkdir /mnt/public $ sudo mount /dev/mmcblk0p2 /mnt/public/ -$ gpg --armor --export $KEYID | sudo tee /mnt/public/$KEYID-$(date +%F).txt +$ gpg --armor --export $KEYID | sudo tee /mnt/public/gpg-$KEYID-$(date +%F).txt ``` **OpenBSD** @@ -1194,7 +1213,7 @@ After some time, the public key will to propagate to [other](https://pgp.key-ser # Configure Smartcard -Use GPG to configure YubiKey as a smartcard: +Plug in a YubiKey and use GPG to configure it as a smartcard: ```console $ gpg --card-edit @@ -1219,6 +1238,8 @@ Authentication key: [none] General key info..: [none] ``` +**Note** If the card is locked, see [Reset](#reset). + **Windows** Use the [YubiKey Manager](https://developers.yubico.com/yubikey-manager) application (note, this not the similarly named older YubiKey NEO Manager) to enable CCID functionality. @@ -2312,7 +2333,7 @@ scd apdu 00 44 00 00 /echo Card has been successfully reset. ``` -Or use `ykman`: +Or use `ykman` (sometimes in `~/.local/bin/`): ```console $ ykman openpgp reset @@ -2368,6 +2389,8 @@ Admin PIN: 12345678 - If you receive the error, `There is no assurance this key belongs to the named user` or `encryption failed: Unusable public key` use `gpg --edit-key` to set `trust` to `5 = I trust ultimately`. +- If you receive the error, `gpg: 0x0000000000000000: skipped: Unusable public key` or `encryption failed: Unusable public key` the sub-key may be expired and can no longer be used to encrypt nor sign messages. It can still be used to decrypt and authenticate, however. + # Links * https://alexcabal.com/creating-the-perfect-gpg-keypair/ From e1055025feda0568ccf2f59ad675fd0b8edd6d85 Mon Sep 17 00:00:00 2001 From: Sebastian Schmieschek Date: Wed, 27 May 2020 10:30:09 +0100 Subject: [PATCH 16/44] Add information on potential PIN issues and how to debug them I missed the error message when attempting to set a PIN of only 5 characters due to the UI repeating the options below it. Pinentry happily stores the bogus PIN and even counts down the retry counter when entering the correct (default) one. This can be resolved by unblocking the PIN. Once I ran the gpg-agent with debug output (a tip found in the added link), the issue was obvious. --- README.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 7547788..93eae2b 100644 --- a/README.md +++ b/README.md @@ -1246,7 +1246,7 @@ Use the [YubiKey Manager](https://developers.yubico.com/yubikey-manager) applica ## Change PIN -The default PIN is `123456` and default Admin PIN (PUK) is `12345678`. CCID-mode PINs can be up to 127 ASCII characters. +The default PIN is `123456` and default Admin PIN (PUK) is `12345678`. CCID-mode PINs can be up to 127 ASCII characters. They have to be at least 6 (PIN) or 8 (PUK) ASCII characters. The Admin PIN is required for some card operations and to unblock a PIN that has been entered incorrectly more than three times. See the GnuPG documentation on [Managing PINs](https://www.gnupg.org/howtos/card-howto/en/ch03s02.html) for details. @@ -2357,9 +2357,11 @@ Admin PIN: 12345678 - Use `man gpg` to understand GPG options and command-line flags. +- To get more information on potential errors, restart the `gpg-agent` process with debug output to the console with `pkill gpg-agent; gpg-agent --daemon --no-detach -v -v --debug-level advanced --homedir ~/.gnupg`. + - If you encounter problems connecting to YubiKey with GPG - try unplugging and re-inserting YubiKey, and restarting the `gpg-agent` process. -- If you receive the error, `gpg: decryption failed: secret key not available` - you likely need to install GnuPG version 2.x. +- If you receive the error, `gpg: decryption failed: secret key not available` - you likely need to install GnuPG version 2.x. Another possibility is that there is a problem with the PIN, e.g. it is too short or blocked. - If you receive the error, `Yubikey core error: no yubikey present` - make sure the YubiKey is inserted correctly. It should blink once when plugged in. @@ -2415,3 +2417,4 @@ Admin PIN: 12345678 * https://www.hanselman.com/blog/HowToSetupSignedGitCommitsWithAYubiKeyNEOAndGPGAndKeybaseOnWindows.aspx * https://www.void.gr/kargig/blog/2013/12/02/creating-a-new-gpg-key-with-subkeys/ * https://mlohr.com/gpg-agent-forwarding/ +* https://www.ingby.com/?p=293 From 78164e8bfdea181cec6186fb5099406030ce19a3 Mon Sep 17 00:00:00 2001 From: Kenny MacDermid Date: Wed, 27 May 2020 16:39:29 -0300 Subject: [PATCH 17/44] Set touch policy to fixed. Setting the touch policy to `on` does not prevent the policy from later being turned off again. Setting it to `fixed` is more secure because it can not be turned off. If someone wants to disable the touch policy they can always restore the keys from the backups created in the guide. --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 93eae2b..c539c25 100644 --- a/README.md +++ b/README.md @@ -2256,19 +2256,19 @@ To require a touch for each key operation, install [YubiKey Manager](https://dev Authentication: ```console -$ ykman openpgp set-touch aut on +$ ykman openpgp set-touch aut fixed ``` Signing: ```console -$ ykman openpgp set-touch sig on +$ ykman openpgp set-touch sig fixed ``` Encryption: ```console -$ ykman openpgp set-touch enc on +$ ykman openpgp set-touch enc fixed ``` YubiKey will blink when it is waiting for a touch. On Linux you can also use [yubikey-touch-detector](https://github.com/maximbaz/yubikey-touch-detector) to have an indicator or notification that YubiKey is waiting for a touch. From f6f2c26e9082c8f4cb3a0e371ab51896b1844566 Mon Sep 17 00:00:00 2001 From: b1f6c1c4 Date: Tue, 11 Aug 2020 02:15:20 -0400 Subject: [PATCH 18/44] Fix usage inconsistency Master key shall only be used to certify other keys. The usage indicator in README.md is inconsistently shown as SC and C. --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index c539c25..315f843 100644 --- a/README.md +++ b/README.md @@ -761,7 +761,7 @@ You selected this USER-ID: "Dr Duh " sec rsa4096/0xFF3E7D88647EBCDB - created: 2017-10-09 expires: never usage: SC + created: 2017-10-09 expires: never usage: C trust: ultimate validity: ultimate ssb rsa4096/0xBECFA3C1AE191D15 created: 2017-10-09 expires: never usage: S @@ -774,7 +774,7 @@ ssb rsa4096/0x3F29127E79649A3D gpg> trust sec rsa4096/0xFF3E7D88647EBCDB - created: 2017-10-09 expires: never usage: SC + created: 2017-10-09 expires: never usage: C trust: ultimate validity: ultimate ssb rsa4096/0xBECFA3C1AE191D15 created: 2017-10-09 expires: never usage: S @@ -799,7 +799,7 @@ Your decision? 5 Do you really want to set this key to ultimate trust? (y/N) y sec rsa4096/0xFF3E7D88647EBCDB - created: 2017-10-09 expires: never usage: SC + created: 2017-10-09 expires: never usage: C trust: ultimate validity: ultimate ssb rsa4096/0xBECFA3C1AE191D15 created: 2017-10-09 expires: never usage: S @@ -813,7 +813,7 @@ ssb rsa4096/0x3F29127E79649A3D gpg> uid 1 sec rsa4096/0xFF3E7D88647EBCDB -created: 2017-10-09 expires: never usage: SC +created: 2017-10-09 expires: never usage: C trust: ultimate validity: ultimate ssb rsa4096/0xBECFA3C1AE191D15 created: 2017-10-09 expires: never usage: S @@ -827,7 +827,7 @@ ssb rsa4096/0x3F29127E79649A3D gpg> primary sec rsa4096/0xFF3E7D88647EBCDB -created: 2017-10-09 expires: never usage: SC +created: 2017-10-09 expires: never usage: C trust: ultimate validity: ultimate ssb rsa4096/0xBECFA3C1AE191D15 created: 2017-10-09 expires: never usage: S From c9ea04db2ce0c7e0bbf50bb82a1fe2924d6925ae Mon Sep 17 00:00:00 2001 From: Stefano Figura Date: Thu, 13 Aug 2020 23:45:18 +0200 Subject: [PATCH 19/44] Add notations section --- README.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/README.md b/README.md index 315f843..13fe760 100644 --- a/README.md +++ b/README.md @@ -47,6 +47,7 @@ If you have a comment or suggestion, please open an [Issue](https://github.com/d * [Setup environment](#setup-environment) * [Renewing sub-keys](#renewing-sub-keys) * [Rotating keys](#rotating-keys-1) +- [Adding notations](#adding-notations) - [SSH](#ssh) * [Create configuration](#create-configuration) * [Replace agents](#replace-agents) @@ -1875,6 +1876,30 @@ $ sudo umount /mnt/public Disconnect the storage device and follow the original steps to transfer new keys (4, 5 and 6) to YubiKey, replacing existing ones. Reboot or securely erase the GPG temporary working directory. +# Adding notations + +Notations can be added to users ID(s) and can be used in conjunction with [Keyoxide](https://keyoxide.org) to create [OpenPGP identity proofs](https://keyoxide.org/guides/openpgp-proofs). + +The setup environment can be created by using this [section](#setup-environment) from this guide. + +After having completed the environment setup, it is possible to follow any of the guides listed under "Adding proofs" from the Keyoxide ["Guides"](https://keyoxide.org/guides/) page __up until the notation is saved using the `save` command`. + +At this point the public key can be exported: + +```console +$ gpg --export $KEYID > pubkey.gpg +``` + +The public key can now be transferred to the computer where the GPG key is used and it is imported with: + +```console +$ gpg --import pubkey.gpg +``` + +N.B.: The `showpref` command can be issued to ensure that the notions were correctly added. + +It is now possible to continue following the Keyoxide guide and upload the key to WKD or to keys.openpgp.org. + # SSH [gpg-agent](https://wiki.archlinux.org/index.php/GnuPG#SSH_agent) supports the OpenSSH ssh-agent protocol (`enable-ssh-support`), as well as Putty's Pageant on Windows (`enable-putty-support`). This means it can be used instead of the traditional ssh-agent / pageant. There are some differences from ssh-agent, notably that gpg-agent does not _cache_ keys rather it converts, encrypts and stores them - persistently - as GPG keys and then makes them available to ssh clients. Any existing ssh private keys that you'd like to keep in `gpg-agent` should be deleted after they've been imported to the GPG agent. From 8a08a8ac151eec600ccd464c219807e79e6371d9 Mon Sep 17 00:00:00 2001 From: Stefano Figura Date: Thu, 13 Aug 2020 23:51:42 +0200 Subject: [PATCH 20/44] Update notation section --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 13fe760..1b1cbd3 100644 --- a/README.md +++ b/README.md @@ -1882,7 +1882,7 @@ Notations can be added to users ID(s) and can be used in conjunction with [Keyox The setup environment can be created by using this [section](#setup-environment) from this guide. -After having completed the environment setup, it is possible to follow any of the guides listed under "Adding proofs" from the Keyoxide ["Guides"](https://keyoxide.org/guides/) page __up until the notation is saved using the `save` command`. +After having completed the environment setup, it is possible to follow any of the guides listed under "Adding proofs" from the Keyoxide ["Guides"](https://keyoxide.org/guides/) page __up until the notation is saved using the `save` command__. At this point the public key can be exported: From a2bc415f84eb73ecd6e280d028f885b84d26905e Mon Sep 17 00:00:00 2001 From: Stefano Figura Date: Fri, 14 Aug 2020 00:06:37 +0200 Subject: [PATCH 21/44] Update wording Ensure that is clear that we do not need to modify keys or even plug the yubikey --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 1b1cbd3..e2b650c 100644 --- a/README.md +++ b/README.md @@ -1880,7 +1880,9 @@ Disconnect the storage device and follow the original steps to transfer new keys Notations can be added to users ID(s) and can be used in conjunction with [Keyoxide](https://keyoxide.org) to create [OpenPGP identity proofs](https://keyoxide.org/guides/openpgp-proofs). -The setup environment can be created by using this [section](#setup-environment) from this guide. +Adding notations requires access to the master key, so we can follow these setup instructions taken from this [section](#setup-environment) from this guide. + +Please note that there is no need to connect the Yubikey to the setup environment and that we do not need to generate new keys, move keys to the YubiKey, or update any SSH public keys linked to the GPG key. After having completed the environment setup, it is possible to follow any of the guides listed under "Adding proofs" from the Keyoxide ["Guides"](https://keyoxide.org/guides/) page __up until the notation is saved using the `save` command__. From 8a95de3e3f5dd5be424fac1cf0826570179e8b9d Mon Sep 17 00:00:00 2001 From: Stefano Figura Date: Fri, 14 Aug 2020 00:12:06 +0200 Subject: [PATCH 22/44] Correct spelling --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index e2b650c..925b133 100644 --- a/README.md +++ b/README.md @@ -1878,13 +1878,13 @@ Disconnect the storage device and follow the original steps to transfer new keys # Adding notations -Notations can be added to users ID(s) and can be used in conjunction with [Keyoxide](https://keyoxide.org) to create [OpenPGP identity proofs](https://keyoxide.org/guides/openpgp-proofs). +Notations can be added to user ID(s) and can be used in conjunction with [Keyoxide](https://keyoxide.org) to create [OpenPGP identity proofs](https://keyoxide.org/guides/openpgp-proofs). -Adding notations requires access to the master key, so we can follow these setup instructions taken from this [section](#setup-environment) from this guide. +Adding notations requires access to the master key so we can follow the setup instructions taken from this [section](#setup-environment) of this guide. Please note that there is no need to connect the Yubikey to the setup environment and that we do not need to generate new keys, move keys to the YubiKey, or update any SSH public keys linked to the GPG key. -After having completed the environment setup, it is possible to follow any of the guides listed under "Adding proofs" from the Keyoxide ["Guides"](https://keyoxide.org/guides/) page __up until the notation is saved using the `save` command__. +After having completed the environment setup, it is possible to follow any of the guides listed under "Adding proofs" in the Keyoxide ["Guides"](https://keyoxide.org/guides/) page __up until the notation is saved using the `save` command__. At this point the public key can be exported: From 58b7c819d72f8596275ec495a9a2e98ec57ae7d5 Mon Sep 17 00:00:00 2001 From: dragon788 Date: Fri, 21 Aug 2020 17:55:28 -0500 Subject: [PATCH 23/44] Python2 is EOL, update packages/references to Py3 --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 315f843..0527800 100644 --- a/README.md +++ b/README.md @@ -211,9 +211,9 @@ $ wget https://raw.githubusercontent.com/drduh/YubiKey-Guide/master/README.md To install and use the `ykman` utility: ```console -$ sudo apt -y install python-pip python-pyscard +$ sudo apt -y install python3-pip python3-pyscard -$ pip install yubikey-manager +$ pip3 install yubikey-manager $ sudo service pcscd start @@ -320,7 +320,7 @@ Most operating systems use software-based pseudorandom number generators. A hard Install and configure OneRNG software: ```console -$ sudo apt -y install at rng-tools python-gnupg openssl +$ sudo apt -y install at rng-tools python3-gnupg openssl $ wget https://github.com/OneRNG/onerng.github.io/raw/master/sw/onerng_3.6-1_all.deb From 2187610c1df9f9866e0bfeddf4879ddf8491499e Mon Sep 17 00:00:00 2001 From: bengim <68807980+bengim@users.noreply.github.com> Date: Sat, 22 Aug 2020 19:33:38 +0400 Subject: [PATCH 24/44] Update README.md fixing wrong cryptography version by explicitly installing PyOpenSSL --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 315f843..200d1e3 100644 --- a/README.md +++ b/README.md @@ -213,6 +213,8 @@ To install and use the `ykman` utility: ```console $ sudo apt -y install python-pip python-pyscard +$ pip install PyOpenSSL + $ pip install yubikey-manager $ sudo service pcscd start From 0e7dabeeeb535ff5dc2e52f8ce443f00812dc508 Mon Sep 17 00:00:00 2001 From: Amolith Date: Wed, 26 Aug 2020 23:42:53 -0400 Subject: [PATCH 25/44] change defaults and add info to #Require touch As mentioned in #197, the previous behaviour would require users to touch their key any time an authentication, signing, or encryption operation was performed. In some situations, this behaviour would be undesirable and the only way to revert it would be fully resetting the key and starting from scratch. Rather than using `fixed`, this commit simply turns the feature `on` so the user can change it later if they wish. Additionally, a note about the other policies was included so users can decide for themselves which fits their situation better. --- README.md | 38 +++++++++++++++++++++++++++++++++++--- 1 file changed, 35 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 915789b..dab25fb 100644 --- a/README.md +++ b/README.md @@ -2285,21 +2285,53 @@ To require a touch for each key operation, install [YubiKey Manager](https://dev Authentication: ```console -$ ykman openpgp set-touch aut fixed +$ ykman openpgp set-touch aut on ``` Signing: ```console -$ ykman openpgp set-touch sig fixed +$ ykman openpgp set-touch sig on ``` Encryption: ```console -$ ykman openpgp set-touch enc fixed +$ ykman openpgp set-touch enc on ``` +Depending on how the YubiKey is going to be used, you may want to look at the policy options for each of these and adjust the above commands accordingly. They can be viewed with the following command: + +``` +$ ykman openpgp set-touch -h +Usage: ykman openpgp set-touch [OPTIONS] KEY POLICY + + Set touch policy for OpenPGP keys. + + KEY Key slot to set (sig, enc, aut or att). + POLICY Touch policy to set (on, off, fixed, cached or cached-fixed). + + The touch policy is used to require user interaction for all operations using the private key on the YubiKey. The touch policy is set indivdually for each key slot. To see the current touch policy, run + + $ ykman openpgp info + + Touch policies: + + Off (default) No touch required + On Touch required + Fixed Touch required, can't be disabled without a full reset + Cached Touch required, cached for 15s after use + Cached-Fixed Touch required, cached for 15s after use, can't be disabled + without a full reset + +Options: + -a, --admin-pin TEXT Admin PIN for OpenPGP. + -f, --force Confirm the action without prompting. + -h, --help Show this message and exit. +``` + +If the YubiKey is going to be used within an email client that opens and verifies encrypted mail, `Cached` or `Cached-Fixed` may be desirable. + YubiKey will blink when it is waiting for a touch. On Linux you can also use [yubikey-touch-detector](https://github.com/maximbaz/yubikey-touch-detector) to have an indicator or notification that YubiKey is waiting for a touch. # Email From 767b84eb3b78e17ecd8829d2e5cf99f9024995f1 Mon Sep 17 00:00:00 2001 From: Mirko Vogt Date: Sat, 29 Aug 2020 16:15:36 +0000 Subject: [PATCH 26/44] Add option to retrieve additionaly entropy from YubiKey itself --- README.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/README.md b/README.md index 915789b..e3df4c8 100644 --- a/README.md +++ b/README.md @@ -320,6 +320,18 @@ $ cat /proc/sys/kernel/random/entropy_avail Most operating systems use software-based pseudorandom number generators. A hardware random number generator like [OneRNG](https://onerng.info/onerng/) will [increase the speed](https://lwn.net/Articles/648550/) of entropy generation and possibly the quality. +From YubiKey firmware version 5.2.3 onwards - which introduces "Enhancements to OpenPGP 3.4 Support" - we can gather additional entropy from the YubiKey itself via the SmartCard interface. + +## YubiKey + +To feed the system's PRNG with entropy generated by the YubiKey itself, issue: +```console +$ echo "SCD RANDOM 512" | gpg-connect-agent | sudo tee /dev/random | hexdump -C +``` +This will seed the Linux kernel's PRNG with additional 512 bytes retrieved from the YubiKey. + +## OneRNG + Install and configure OneRNG software: ```console @@ -2447,3 +2459,4 @@ Admin PIN: 12345678 * https://www.void.gr/kargig/blog/2013/12/02/creating-a-new-gpg-key-with-subkeys/ * https://mlohr.com/gpg-agent-forwarding/ * https://www.ingby.com/?p=293 +* https://support.yubico.com/support/solutions/articles/15000027139-yubikey-5-2-3-enhancements-to-openpgp-3-4-support From 1698736906dfd952158ba7b00c66c1f0c0bcf10d Mon Sep 17 00:00:00 2001 From: drduh Date: Sun, 30 Aug 2020 21:06:04 +0000 Subject: [PATCH 27/44] Create FUNDING.yml --- .github/FUNDING.yml | 1 + 1 file changed, 1 insertion(+) create mode 100644 .github/FUNDING.yml diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml new file mode 100644 index 0000000..92cbba9 --- /dev/null +++ b/.github/FUNDING.yml @@ -0,0 +1 @@ +github: [drduh] From 547c1267bca2579b7f8d96b1c613b07ff278a1c3 Mon Sep 17 00:00:00 2001 From: Rudy Gevaert <66934+rgevaert@users.noreply.github.com> Date: Tue, 1 Sep 2020 14:20:32 +0200 Subject: [PATCH 28/44] unset GNUPGHOME variable if not done, in the next step you get error: gpg: keyblock resource '/home/..../gnupg-workspace/pubring.kbx': No such file or directory gpg: no writable keyring found: Not found --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index f84f660..6d48413 100644 --- a/README.md +++ b/README.md @@ -1500,6 +1500,8 @@ Reboot or [securely delete](http://srm.sourceforge.net/) `$GNUPGHOME` and remove $ sudo srm -r $GNUPGHOME || sudo rm -rf $GNUPGHOME $ gpg --delete-secret-key $KEYID + +$ unset GNUPGHOME ``` **Important** Make sure you have securely erased all generated keys and revocation certificates if an ephemeral enviroment was not used! From f0e877fe5f01515ae1c42c515189160746a2c9ec Mon Sep 17 00:00:00 2001 From: andy Date: Thu, 17 Sep 2020 19:31:00 -0400 Subject: [PATCH 29/44] Fix links with parentheses --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index f84f660..5a94194 100644 --- a/README.md +++ b/README.md @@ -52,10 +52,10 @@ If you have a comment or suggestion, please open an [Issue](https://github.com/d * [Create configuration](#create-configuration) * [Replace agents](#replace-agents) * [Copy public key](#copy-public-key) - * [(Optional) Save public key for identity file configuration](#-optional--save-public-key-for-identity-file-configuration) + * [(Optional) Save public key for identity file configuration](#optional-save-public-key-for-identity-file-configuration) * [Connect with public key authentication](#connect-with-public-key-authentication) * [Import SSH keys](#import-ssh-keys) - * [Remote Machines (Agent Forwarding)](#remote-machines--agent-forwarding-) + * [Remote Machines (Agent Forwarding)](#remote-machines-agent-forwarding) + [Steps for older distributions](#steps-for-older-distributions) * [GitHub](#github) * [OpenBSD](#openbsd-1) From 967ca3cc529052525eb9475e20ff624082f2f8b6 Mon Sep 17 00:00:00 2001 From: Anthony Muller <57217388+anmull@users.noreply.github.com> Date: Fri, 25 Sep 2020 08:18:44 +0000 Subject: [PATCH 30/44] Change Debian ISO url to be generated from the contents of SHA512SUM. This removes the need to maintain the version number, which is currently out of date. --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index f84f660..b5130ae 100644 --- a/README.md +++ b/README.md @@ -101,11 +101,11 @@ This guide recommends using a bootable "live" Debian Linux image to provide such To use Debian Live, download the latest image: ```console -$ curl -LfO https://cdimage.debian.org/debian-cd/current-live/amd64/iso-hybrid/debian-live-10.4.0-amd64-xfce.iso - $ curl -LfO https://cdimage.debian.org/debian-cd/current-live/amd64/iso-hybrid/SHA512SUMS $ curl -LfO https://cdimage.debian.org/debian-cd/current-live/amd64/iso-hybrid/SHA512SUMS.sign + +$ curl -LfO https://cdimage.debian.org/debian-cd/current-live/amd64/iso-hybrid/$(awk '/xfce.iso/ {print $2}' SHA512SUMS) ``` Verify the signature of the hashes file with GPG: From 70dc01467b182c2c88a7285cbd2fd88caaf414e8 Mon Sep 17 00:00:00 2001 From: Anthony Muller <57217388+anmull@users.noreply.github.com> Date: Fri, 25 Sep 2020 18:11:40 +0000 Subject: [PATCH 31/44] Update verification of Debian ISO to not hardcode the version. --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index b5130ae..afff133 100644 --- a/README.md +++ b/README.md @@ -139,8 +139,8 @@ $ gpg --keyserver hkps://keyserver.ubuntu.com:443 --recv DF9B9C49EAA9298432589D7 Ensure the SHA512 hash of the live image matches the one in the signed file. ```console -$ grep $(sha512sum debian-live-10.4.0-amd64-xfce.iso) SHA512SUMS -SHA512SUMS:2920f398c5e9036fcec8f71b2f28b0f2a85e3ab805e66088192dc56f679e5f59f26634e8bbde70badc3cf7ce353f54a2757b2017cbc3d3df9fb2b2065b3c1041 debian-live-10.4.0-amd64-xfce.iso +$ grep $(sha512sum debian-live-*-amd64-xfce.iso) SHA512SUMS +SHA512SUMS:799ec1fdb098caa7b60b71ed1fdb1f6390a1c6717b4314265e7042fa271c84f67fff0d0380297f60c4bcd0c1001e08623ab3d2a2ad64079d83d1795c40eb7a0a debian-live-10.5.0-amd64-xfce.iso ``` See [Verifying authenticity of Debian CDs](https://www.debian.org/CD/verify) for more information. From fd4b6f3eb46e90ce34a34585831a5b3fb6079922 Mon Sep 17 00:00:00 2001 From: Jean-Paul van Ravensberg <14926452+DevSecNinja@users.noreply.github.com> Date: Sat, 31 Oct 2020 11:15:51 +0100 Subject: [PATCH 32/44] Add PowerShell command to get YubiKey name --- README.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index f84f660..684ffc6 100644 --- a/README.md +++ b/README.md @@ -2162,12 +2162,19 @@ $ doas reboot ## Windows -Windows can already have some virtual smartcard readers installed, like the one provided for Windows Hello. To ensure your YubiKey is the correct one used by scdaemon, you should add it to its configuration. You will need your device's full name. To find out what is your device's full name, plug your YubiKey, open the Device Manager, select "View > Show hidden devices". Go to the Software Devices list, you should see something like `Yubico YubiKey OTP+FIDO+CCID 0`. The name slightly differs according to the model. Thanks to [Scott Hanselman](https://www.hanselman.com/blog/HowToSetupSignedGitCommitsWithAYubiKeyNEOAndGPGAndKeybaseOnWindows.aspx) for sharing this information. +Windows can already have some virtual smartcard readers installed, like the one provided for Windows Hello. To ensure your YubiKey is the correct one used by scdaemon, you should add it to its configuration. You will need your device's full name. To find out what is your device's full name, plug your YubiKey and open PowerShell to run the following command: + +```` powershell +PS C:\WINDOWS\system32> Get-PnpDevice -Class SoftwareDevice | Where-Object {$_.FriendlyName -like "*YubiKey*"} | Select-Object -ExpandProperty FriendlyName +Yubico YubiKey OTP+FIDO+CCID 0 +```` + +The name slightly differs according to the model. Thanks to [Scott Hanselman](https://www.hanselman.com/blog/HowToSetupSignedGitCommitsWithAYubiKeyNEOAndGPGAndKeybaseOnWindows.aspx) for sharing this information. * Create or edit `%APPDATA%/gnupg/scdaemon.conf` to add: ``` -reader-port +reader-port ``` * Edit `%APPDATA%/gnupg/gpg-agent.conf` to add: From b1d3d279eb932f5ea3f0854a48567911f8524f11 Mon Sep 17 00:00:00 2001 From: Jean-Paul van Ravensberg <14926452+DevSecNinja@users.noreply.github.com> Date: Sat, 31 Oct 2020 11:29:35 +0100 Subject: [PATCH 33/44] Change edit to create or edit As gpg-agent.conf didn't exist on my system --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 684ffc6..2a96a63 100644 --- a/README.md +++ b/README.md @@ -2177,7 +2177,7 @@ The name slightly differs according to the model. Thanks to [Scott Hanselman](ht reader-port ``` -* Edit `%APPDATA%/gnupg/gpg-agent.conf` to add: +* Create or edit `%APPDATA%/gnupg/gpg-agent.conf` to add: ``` enable-ssh-support From 7067ba6c38589e902ba679ad3f2df37c6ef86a94 Mon Sep 17 00:00:00 2001 From: Nemo Date: Sat, 14 Nov 2020 09:24:19 +0000 Subject: [PATCH 34/44] Fix reset command gpg-connect-agent uses `-r/--run` not `-R` --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 7374c54..bf89932 100644 --- a/README.md +++ b/README.md @@ -2396,7 +2396,7 @@ Finally, install the [Mailvelope extension](https://chrome.google.com/webstore/d If PIN attempts are exceeded, the card is locked and must be [reset](https://developers.yubico.com/ykneo-openpgp/ResetApplet.html) and set up again using the encrypted backup. -Copy the following script to a file and run `gpg-connect-agent -R $file` to lock and terminate the card. Then re-insert YubiKey to reset. +Copy the following script to a file and run `gpg-connect-agent --run $file` to lock and terminate the card. Then re-insert YubiKey to reset. ```console /hex From 0ea32bb9492dec9fc1b25bd4b747b4906508cc42 Mon Sep 17 00:00:00 2001 From: Zenithal Date: Wed, 2 Dec 2020 22:35:56 +0800 Subject: [PATCH 35/44] Add Mutt in Email intro --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 47f5c0b..85247ef 100644 --- a/README.md +++ b/README.md @@ -2365,7 +2365,7 @@ YubiKey will blink when it is waiting for a touch. On Linux you can also use [yu # Email -GPG keys on YubiKey can be used with ease to encrypt and/or sign emails and attachments using [Thunderbird](https://www.thunderbird.net/) and [Enigmail](https://www.enigmail.net). Thunderbird supports OAuth 2 authentication and can be used with Gmail. See [this guide](https://ssd.eff.org/en/module/how-use-pgp-linux) from EFF for detailed instructions. +GPG keys on YubiKey can be used with ease to encrypt and/or sign emails and attachments using [Thunderbird](https://www.thunderbird.net/), [Enigmail](https://www.enigmail.net) and [Mutt](http://www.mutt.org/). Thunderbird supports OAuth 2 authentication and can be used with Gmail. See [this guide](https://ssd.eff.org/en/module/how-use-pgp-linux) from EFF for detailed instructions. Mutt has OAuth 2 support since version 2.0. ## Mailvelope on macOS From 083aa53cf0e85ed5c927d17946e2ffe559beed33 Mon Sep 17 00:00:00 2001 From: Zenithal Date: Wed, 2 Dec 2020 22:59:30 +0800 Subject: [PATCH 36/44] Add Mutt subsection in Email section --- README.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/README.md b/README.md index 85247ef..fc3cf7f 100644 --- a/README.md +++ b/README.md @@ -68,6 +68,7 @@ If you have a comment or suggestion, please open an [Issue](https://github.com/d - [Require touch](#require-touch) - [Email](#email) * [Mailvelope on macOS](#mailvelope-on-macos) + * [Mutt](#mutt) - [Reset](#reset) - [Notes](#notes) - [Troubleshooting](#troubleshooting) @@ -2401,6 +2402,14 @@ $ sudo launchctl config user path /usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin Finally, install the [Mailvelope extension](https://chrome.google.com/webstore/detail/mailvelope/kajibbejlbohfaggdiogboambcijhkke) from the Chrome app store. +## Mutt + +Mutt has both CLI and TUI interfaces, and the latter provides powerful functions for daily email processing. In addition, PGP can be integrated such that signing/encryption/verifying/decryption can be done without leaving TUI. + +To enable GnuPG support, one can just use the config file `gpg.rc` provided by mutt, usually located at `/usr/share/doc/mutt/samples/gpg.rc` after installation. One only needs to edit the file on options like `pgp_default_key`, `pgp_sign_as` and `pgp_autosign`. After editting one can `source` this rcfile in their main `muttrc` to use it. + +Note that if one uses `pinentry-tty` as one's pinentry program in `gpg-agent.conf`, it would mess with one's Mutt TUI, as reported. This is because Mutt TUI uses curses while tty output may harm the format. It is recommended to use `pinentry-curses` or other graphic pinentry program. + # Reset If PIN attempts are exceeded, the card is locked and must be [reset](https://developers.yubico.com/ykneo-openpgp/ResetApplet.html) and set up again using the encrypted backup. From 410a1d6ac2c15dfeebb7508c3a4c2dab08e1b2b9 Mon Sep 17 00:00:00 2001 From: Zenithal Date: Wed, 2 Dec 2020 23:23:34 +0800 Subject: [PATCH 37/44] Change format of important notes in mutt subsection --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index fc3cf7f..e26b7be 100644 --- a/README.md +++ b/README.md @@ -2408,7 +2408,7 @@ Mutt has both CLI and TUI interfaces, and the latter provides powerful functions To enable GnuPG support, one can just use the config file `gpg.rc` provided by mutt, usually located at `/usr/share/doc/mutt/samples/gpg.rc` after installation. One only needs to edit the file on options like `pgp_default_key`, `pgp_sign_as` and `pgp_autosign`. After editting one can `source` this rcfile in their main `muttrc` to use it. -Note that if one uses `pinentry-tty` as one's pinentry program in `gpg-agent.conf`, it would mess with one's Mutt TUI, as reported. This is because Mutt TUI uses curses while tty output may harm the format. It is recommended to use `pinentry-curses` or other graphic pinentry program. +**Important** If one uses `pinentry-tty` as one's pinentry program in `gpg-agent.conf`, it would mess with one's Mutt TUI, as reported. This is because Mutt TUI uses curses while tty output may harm the format. It is recommended to use `pinentry-curses` or other graphic pinentry program. # Reset From 54f9e8a3f960ce10e92e9ef18abb7703062922e2 Mon Sep 17 00:00:00 2001 From: Zenithal Date: Thu, 3 Dec 2020 00:13:15 +0800 Subject: [PATCH 38/44] Add details to GPG-Agent forward; Alter structure GPG Agent forwarding has a broader usage, not only limited to ssh-agent forwarding. In this commit gpg-agent forwarding is raised as a separate section as it can not be contained by #SSH any longer. More details are added for gpg-agent forwarding, including some important notes taken from practice and analysis. For ssh-agent forward, older method are contained, and new method will be included as framework has been structured. --- README.md | 129 ++++++++++++++++++++++++++++++------------------------ 1 file changed, 73 insertions(+), 56 deletions(-) diff --git a/README.md b/README.md index 47f5c0b..69ed792 100644 --- a/README.md +++ b/README.md @@ -55,8 +55,7 @@ If you have a comment or suggestion, please open an [Issue](https://github.com/d * [(Optional) Save public key for identity file configuration](#optional-save-public-key-for-identity-file-configuration) * [Connect with public key authentication](#connect-with-public-key-authentication) * [Import SSH keys](#import-ssh-keys) - * [Remote Machines (Agent Forwarding)](#remote-machines-agent-forwarding) - + [Steps for older distributions](#steps-for-older-distributions) + * [Remote machines (SSH Agent Forwarding)](#remote-machines-ssh-agent-forwarding) * [GitHub](#github) * [OpenBSD](#openbsd-1) * [Windows](#windows-1) @@ -64,6 +63,8 @@ If you have a comment or suggestion, please open an [Issue](https://github.com/d - [Prerequisites](#prerequisites) - [WSL configuration](#wsl-configuration) - [Remote host configuration](#remote-host-configuration) +- [Remote Machines (Agent Forwarding)](#remote-machines-agent-forwarding) + * [Steps for older distributions](#steps-for-older-distributions) - [Using Multiple Keys](#using-multiple-keys) - [Require touch](#require-touch) - [Email](#email) @@ -2070,66 +2071,15 @@ $ ssh-add -E md5 -l When using the key `pinentry` will be invoked to request the key's passphrase. The passphrase will be cached for up to 10 minutes idle time between uses, to a maximum of 2 hours. -## Remote Machines (Agent Forwarding) +## Remote Machines (SSH Agent Forwarding) **Note** SSH Agent Forwarding can [add additional risk](https://matrix.org/blog/2019/05/08/post-mortem-and-remediations-for-apr-11-security-incident/#ssh-agent-forwarding-should-be-disabled) - proceed with caution! -To use YubiKey to sign a git commit on a remote host, or ssh through another network, configure and use Agent Forwarding. - -To do this, you need access to the remote machine and the YubiKey has to be set up on the host machine. - -On the remote machine, edit `/etc/ssh/sshd_config` to set `StreamLocalBindUnlink yes` - -**Optional** If you do not have root access to the remote machine to edit `/etc/ssh/sshd_config`, you will need to remove the socket on the remote machine before forwarding works. For example, `rm /run/user/1000/gnupg/S.gpg-agent`. Further information can be found on the [AgentForwarding GNUPG wiki page](https://wiki.gnupg.org/AgentForwarding). - -Import public keys to the remote machine. This can be done by fetching from a keyserver. On the local machine, copy the public keyring to the remote machine: - -```console -$ scp ~/.gnupg/pubring.kbx remote:~/.gnupg/ -``` +### Use ssh-agent You should now be able use `ssh -A remote` on the _local_ machine to log into _remote_, and should then be able to use YubiKey as if it were connected to the remote machine. For example, using e.g. `ssh-add -l` on that remote machine should show the public key from the YubiKey (note `cardno:`). (If you don't want to have to remember to use `ssh -A`, you can use `ForwardAgent yes` in `~/.ssh/config`. As a security best practice, always use `ForwardAgent yes` only for a single `Hostname`, never for all servers.) -On modern distributions, such as Fedora 30, there is typically no need to also set `RemoteForward` in `~/.ssh/config` as detailed in the next chapter, because the right thing actually happens automatically. - - -### Steps for older distributions - -On the local machine, run: - -```console -$ gpgconf --list-dirs agent-extra-socket -``` - -This should return a path to agent-extra-socket - `/run/user/1000/gnupg/S.gpg-agent.extra` - though on older Linux distros (and macOS) it may be `/home//.gnupg/S/gpg-agent.extra` - -Find the agent socket on the **remote** machine: - -```console -$ gpgconf --list-dirs agent-socket -``` - -This should return a path such as `/run/user/1000/gnupg/S.gpg-agent` - -Finally, enable agent forwarding for a given machine by adding the following to the local machine's ssh config file `~/.ssh/config` (your agent sockets may be different): - -``` -Host - Hostname remote-host.tld - ForwardAgent yes - RemoteForward /run/user/1000/gnupg/S.gpg-agent /run/user/1000/gnupg/S.gpg-agent.extra - # RemoteForward [remote socket] [local socket] -``` - -If you're still having problems, it may be necessary to edit `gpg-agent.conf` file on both the remote and local machines to add the following information: - -``` -enable-ssh-support -pinentry-program /usr/bin/pinentry-curses -extra-socket /run/user/1000/gnupg/S.gpg-agent.extra -``` - -See [Issue #85](https://github.com/drduh/YubiKey-Guide/issues/85) for more information and troubleshooting. +### Use S.gpg-agent.ssh ## GitHub @@ -2271,6 +2221,73 @@ On the remote host, type `ssh-add -l` - if you see the ssh key, that means forwa **Note** Agent forwarding may be chained through multiple hosts - just follow the same [protocol](#remote-host-configuration) to configure each host. +# Remote Machines (Agent Forwarding) + +This section is different from ssh-agent forwarding in [SSH](#ssh) as gpg-agent forwarding has a broader usage, not only limited to ssh. + +To use YubiKey to sign a git commit on a remote host, or signing email/decrypt files on a remote host, configure and use GPG Agent Forwarding. To ssh through another network, especially to push to/pull from GitHub using ssh, see [Remote Machines](#SSH Agent Forwarding) for more info. + +To do this, you need access to the remote machine and the YubiKey has to be set up on the host machine. + +After gpg-agent forwarding, it is nearly the same as if YubiKey was inserted in the remote. Hence configurations except `gpg-agent.conf` for the remote can be the same as those for the local. + +**Important** `gpg-agent.conf` for the remote is of no use, hence `$GPG_TTY` is of no use too for the remote. The mechanism is that after forwarding, remote `gpg` directly communicates with `S.gpg-agent` without *starting* `gpg-agent` on the remote. + +On the remote machine, edit `/etc/ssh/sshd_config` to set `StreamLocalBindUnlink yes` + +**Optional** If you do not have root access to the remote machine to edit `/etc/ssh/sshd_config`, you will need to remove the socket (located at `gpgconf --list-dir agent-socket`) on the remote machine before forwarding works. For example, `rm /run/user/1000/gnupg/S.gpg-agent`. Further information can be found on the [AgentForwarding GNUPG wiki page](https://wiki.gnupg.org/AgentForwarding). + +Import public keys to the remote machine. This can be done by fetching from a keyserver. On the local machine, copy the public keyring to the remote machine: + +```console +$ scp ~/.gnupg/pubring.kbx remote:~/.gnupg/ +``` + +On modern distributions, such as Fedora 30, there is typically no need to also set `RemoteForward` in `~/.ssh/config` as detailed in the next chapter, because the right thing actually happens automatically. + +If any error happens (or there is no `gpg-agent.socket` in the remote) for modern distributions, you may go through the configuration steps in the next section. + +## Steps for older distributions + +On the local machine, run: + +```console +$ gpgconf --list-dirs agent-extra-socket +``` + +This should return a path to agent-extra-socket - `/run/user/1000/gnupg/S.gpg-agent.extra` - though on older Linux distros (and macOS) it may be `/home//.gnupg/S/gpg-agent.extra` + +Find the agent socket on the **remote** machine: + +```console +$ gpgconf --list-dirs agent-socket +``` + +This should return a path such as `/run/user/1000/gnupg/S.gpg-agent` + +Finally, enable agent forwarding for a given machine by adding the following to the local machine's ssh config file `~/.ssh/config` (your agent sockets may be different): + +``` +Host + Hostname remote-host.tld + StreamLocalBindUnlink yes + RemoteForward /run/user/1000/gnupg/S.gpg-agent /run/user/1000/gnupg/S.gpg-agent.extra + # RemoteForward [remote socket] [local socket] +``` + +If you're still having problems, it may be necessary to edit `gpg-agent.conf` file on the *local* machines to add the following information: + +``` +pinentry-program /usr/bin/pinentry-gtk-2 +extra-socket /run/user/1000/gnupg/S.gpg-agent.extra +``` + +**Note** The pinentry program starts on *local* machine, not remote. Hence when there are needs to enter the pin you need to find the prompt on local machine. + +**Important** Any pinentry program except `pinentry-tty` or `pinentry-curses` may be used. This is because local `gpg-agent` may start headlessly (By systemd without `$GPG_TTY` set locally telling which tty it is on), thus failed to obtain the pin. Errors on the remote may be misleading saying that there is *IO Error* (Yes internally there is actually *IO Error* since it happens when writing to/reading from tty while finding no tty to use, but for end users this is not friendly). + +See [Issue #85](https://github.com/drduh/YubiKey-Guide/issues/85) for more information and troubleshooting. + # Using Multiple Keys To use a single identity with multiple YubiKeys - or to replace a lost card with another - issue this command to switch keys: From 0d06d2ace875483d077b89dd1c0568986ec7266d Mon Sep 17 00:00:00 2001 From: Zenithal Date: Thu, 3 Dec 2020 00:52:43 +0800 Subject: [PATCH 39/44] Add new method for ssh-agent forwarding --- README.md | 49 +++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 45 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 69ed792..6b63d61 100644 --- a/README.md +++ b/README.md @@ -56,6 +56,8 @@ If you have a comment or suggestion, please open an [Issue](https://github.com/d * [Connect with public key authentication](#connect-with-public-key-authentication) * [Import SSH keys](#import-ssh-keys) * [Remote machines (SSH Agent Forwarding)](#remote-machines-ssh-agent-forwarding) + - [Use ssh-agent](#use-ssh-agent) + - [Use S.gpg-agent.ssh](#use-sgpg-agentssh) * [GitHub](#github) * [OpenBSD](#openbsd-1) * [Windows](#windows-1) @@ -63,7 +65,7 @@ If you have a comment or suggestion, please open an [Issue](https://github.com/d - [Prerequisites](#prerequisites) - [WSL configuration](#wsl-configuration) - [Remote host configuration](#remote-host-configuration) -- [Remote Machines (Agent Forwarding)](#remote-machines-agent-forwarding) +- [Remote Machines (GPG Agent Forwarding)](#remote-machines-gpg-agent-forwarding) * [Steps for older distributions](#steps-for-older-distributions) - [Using Multiple Keys](#using-multiple-keys) - [Require touch](#require-touch) @@ -1977,7 +1979,7 @@ export SSH_AUTH_SOCK=$(gpgconf --list-dirs agent-ssh-socket) gpgconf --launch gpg-agent ``` -Note that `SSH_AUTH_SOCK` normally only needs to be set on the *local* laptop (workstation), where the YubiKey is plugged in. On the *remote* server that we SSH into, `ssh` will automatically set `SSH_AUTH_SOCK` to something like `/tmp/ssh-mXzCzYT2Np/agent.7541` when we connect. We therefore do **NOT** manually set `SSH_AUTH_SOCK` on the server - doing so would break [SSH Agent Forwarding](#remote-machines-agent-forwarding). +Note that `SSH_AUTH_SOCK` normally only needs to be set on the *local* laptop (workstation), where the YubiKey is plugged in. On the *remote* server that we SSH into, `ssh` will automatically set `SSH_AUTH_SOCK` to something like `/tmp/ssh-mXzCzYT2Np/agent.7541` when we connect. We therefore do **NOT** manually set `SSH_AUTH_SOCK` on the server - doing so would break [SSH Agent Forwarding](#remote-machines-gpg-agent-forwarding). ## Copy public key @@ -2075,12 +2077,51 @@ When using the key `pinentry` will be invoked to request the key's passphrase. T **Note** SSH Agent Forwarding can [add additional risk](https://matrix.org/blog/2019/05/08/post-mortem-and-remediations-for-apr-11-security-incident/#ssh-agent-forwarding-should-be-disabled) - proceed with caution! +There are two methods for ssh-agent forwarding, one is provided by OpenSSH and the other is provided by GnuPG. + +The latter one may be more insecure as raw socket is just forwarded (not like `S.gpg-agent.extra` with only limited functionality; if `ForwardAgent` implemented by OpenSSH is just forwarding the raw socket, then they are insecure to the same degree). But for the latter one, one convenience is that one may forward once and use this agent everywhere in the remote. So again, proceed with caution! + +For example, `tmux` does not have some environment variables like `$SSH_AUTH_SOCK` when you ssh into remote and attach an old `tmux` session. In this case if you use `ForwardAgent`, you need to find the socket manually and `export SSH_AUTH_SOCK=/tmp/ssh-agent-xxx/xxxx.socket` for each shell. But with `S.gpg-agent.ssh` in fixed place, one can just use it as ssh-agent in their shell rc file. + ### Use ssh-agent +In the above steps, you have successfully configured a local ssh-agent. + You should now be able use `ssh -A remote` on the _local_ machine to log into _remote_, and should then be able to use YubiKey as if it were connected to the remote machine. For example, using e.g. `ssh-add -l` on that remote machine should show the public key from the YubiKey (note `cardno:`). (If you don't want to have to remember to use `ssh -A`, you can use `ForwardAgent yes` in `~/.ssh/config`. As a security best practice, always use `ForwardAgent yes` only for a single `Hostname`, never for all servers.) ### Use S.gpg-agent.ssh +First you need to go through [Remote Machines (GPG Agent Forwarding)](#remote-machines-gpg-agent-forwarding), know the conditions for gpg-agent forwarding and know the location of `S.gpg-agent.ssh` on both the local and the remote. + +You may use the command: + +```console +$ gpgconf --list-dirs agent-ssh-socket +``` + +Then in your `.ssh/config` add one sentence for that remote + +``` +Host + Hostname remote-host.tld + StreamLocalBindUnlink yes + RemoteForward /run/user/1000/gnupg/S.gpg-agent.ssh /run/user/1000/gnupg/S.gpg-agent.ssh + # RemoteForward [remote socket] [local socket] + # Note that ForwardAgent is not wanted here! +``` + +After successfully ssh into the remote, you should check that you have `/run/user/1000/gnupg/S.gpg-agent.ssh` lying there. + +The in the *remote* you can type in command line or configure in the shell rc file with + +```console +export SSH_AUTH_SOCK="/run/user/$UID/gnupg/S.gpg-agent.ssh" +``` + +After typing or sourcing your shell rc file, with `ssh-add -l` you should find your ssh public key now. + +**Note** In this process no gpg-agent in the remote is involved, hence `gpg-agent.conf` in the remote is of no use. Also pinentry is invoked locally. + ## GitHub You can use YubiKey to sign GitHub commits and tags. It can also be used for GitHub SSH authentication, allowing you to push, pull, and commit without a password. @@ -2221,11 +2262,11 @@ On the remote host, type `ssh-add -l` - if you see the ssh key, that means forwa **Note** Agent forwarding may be chained through multiple hosts - just follow the same [protocol](#remote-host-configuration) to configure each host. -# Remote Machines (Agent Forwarding) +# Remote Machines (GPG Agent Forwarding) This section is different from ssh-agent forwarding in [SSH](#ssh) as gpg-agent forwarding has a broader usage, not only limited to ssh. -To use YubiKey to sign a git commit on a remote host, or signing email/decrypt files on a remote host, configure and use GPG Agent Forwarding. To ssh through another network, especially to push to/pull from GitHub using ssh, see [Remote Machines](#SSH Agent Forwarding) for more info. +To use YubiKey to sign a git commit on a remote host, or signing email/decrypt files on a remote host, configure and use GPG Agent Forwarding. To ssh through another network, especially to push to/pull from GitHub using ssh, see [Remote Machines (SSH Agent forwarding)](#remote-machines-ssh-agent-forwarding) for more info. To do this, you need access to the remote machine and the YubiKey has to be set up on the host machine. From 6097e6762cbba92ea272a29266e0edce8e440044 Mon Sep 17 00:00:00 2001 From: Zenithal Date: Thu, 3 Dec 2020 01:01:36 +0800 Subject: [PATCH 40/44] Change note in alter agent section Different methods have different requirements --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 6b63d61..e5823bc 100644 --- a/README.md +++ b/README.md @@ -1979,8 +1979,9 @@ export SSH_AUTH_SOCK=$(gpgconf --list-dirs agent-ssh-socket) gpgconf --launch gpg-agent ``` -Note that `SSH_AUTH_SOCK` normally only needs to be set on the *local* laptop (workstation), where the YubiKey is plugged in. On the *remote* server that we SSH into, `ssh` will automatically set `SSH_AUTH_SOCK` to something like `/tmp/ssh-mXzCzYT2Np/agent.7541` when we connect. We therefore do **NOT** manually set `SSH_AUTH_SOCK` on the server - doing so would break [SSH Agent Forwarding](#remote-machines-gpg-agent-forwarding). +Note that if you use `ForwardAgent` for ssh-agent forwarding, `SSH_AUTH_SOCK` only needs to be set on the *local* laptop (workstation), where the YubiKey is plugged in. On the *remote* server that we SSH into, `ssh` will automatically set `SSH_AUTH_SOCK` to something like `/tmp/ssh-mXzCzYT2Np/agent.7541` when we connect. We therefore do **NOT** manually set `SSH_AUTH_SOCK` on the server - doing so would break [SSH Agent Forwarding](#remote-machines-ssh-agent-forwarding). +If you use `S.gpg-agent.ssh` (see [SSH Agent Forwarding](#remote-machines-ssh-agent-forwarding) for more info), `SSH_AUTH_SOCK` should also be set on the *remote*. However, `GPG_TTY` should not be set on the *remote*, explanation specified in that section. ## Copy public key From 52727f1e045be51dde04b9c2ddbcbb784799e668 Mon Sep 17 00:00:00 2001 From: Zenithal Date: Thu, 3 Dec 2020 01:16:47 +0800 Subject: [PATCH 41/44] Correct WSL agent forwarding This is a mix of two forwarding method, this commit separates them --- README.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index e5823bc..7e052ae 100644 --- a/README.md +++ b/README.md @@ -62,6 +62,7 @@ If you have a comment or suggestion, please open an [Issue](https://github.com/d * [OpenBSD](#openbsd-1) * [Windows](#windows-1) + [WSL](#wsl) + - [Use ssh-agent or use S.weasel-pegant](#use-ssh-agent-or-use-sweasel-pegant) - [Prerequisites](#prerequisites) - [WSL configuration](#wsl-configuration) - [Remote host configuration](#remote-host-configuration) @@ -2212,6 +2213,12 @@ The goal here is to make the SSH client inside WSL work together with the Window **Note** this works only for SSH agent forwarding. Real GPG forwarding (encryption/decryption) is actually not supported. See the [weasel-pageant](https://github.com/vuori/weasel-pageant) readme for further information. +#### Use ssh-agent or use S.weasel-pegant + +One way to forward is just `ssh -A` (still need to eval weasel to setup local ssh-agent), and only relies on OpenSSH. In this track, `ForwardAgent` and `AllowAgentForwarding` may be involved. Otherwise they are of no use or even harm the forwarding. See [SSH Agent Forwarding](#remote-machines-ssh-agent-forwarding) for more info. + +Another way is to forward the gpg ssh socket, as described below. + #### Prerequisites * Ubuntu 16.04 or newer for WSL @@ -2229,7 +2236,6 @@ Display the SSH key with `$ ssh-add -l` Edit `~/.ssh/config` to add the following for each host you want to use agent forwarding: ``` -ForwardAgent yes RemoteForward /tmp/S.weasel-pageant ``` @@ -2237,17 +2243,15 @@ RemoteForward /tmp/S.weasel-pageant #### Remote host configuration -You may have to add the following to the shell rc file. On Linux, this is only required on the laptop/workstation where the YubiKey is plugged in, and **NOT** on the remote host server that you connect to; in fact at least on some Linux distributions, changing SSH_AUTH_SOCK on the server breaks agent forwarding. +You may have to add the following to the shell rc file. ``` export SSH_AUTH_SOCK=$(gpgconf --list-dirs agent-ssh-socket) -export GPG_TTY=$(tty) ``` Add the following to `/etc/ssh/sshd_config`: ``` -AllowAgentForwarding yes StreamLocalBindUnlink yes ``` From 7e49f5cc89cafcfd665375f5fde72e2a38039d04 Mon Sep 17 00:00:00 2001 From: Zenithal Date: Thu, 3 Dec 2020 01:18:21 +0800 Subject: [PATCH 42/44] Add note on chained agent forwarding --- README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.md b/README.md index 7e052ae..1b2bef0 100644 --- a/README.md +++ b/README.md @@ -2124,6 +2124,8 @@ After typing or sourcing your shell rc file, with `ssh-add -l` you should find y **Note** In this process no gpg-agent in the remote is involved, hence `gpg-agent.conf` in the remote is of no use. Also pinentry is invoked locally. +**Note** Agent forwarding may be chained through multiple hosts + ## GitHub You can use YubiKey to sign GitHub commits and tags. It can also be used for GitHub SSH authentication, allowing you to push, pull, and commit without a password. @@ -2332,6 +2334,8 @@ extra-socket /run/user/1000/gnupg/S.gpg-agent.extra **Important** Any pinentry program except `pinentry-tty` or `pinentry-curses` may be used. This is because local `gpg-agent` may start headlessly (By systemd without `$GPG_TTY` set locally telling which tty it is on), thus failed to obtain the pin. Errors on the remote may be misleading saying that there is *IO Error* (Yes internally there is actually *IO Error* since it happens when writing to/reading from tty while finding no tty to use, but for end users this is not friendly). +**Note** Agent forwarding may be chained through multiple hosts + See [Issue #85](https://github.com/drduh/YubiKey-Guide/issues/85) for more information and troubleshooting. # Using Multiple Keys From a24fa8f373c5d41ef6266a0342cc31ababb47ed6 Mon Sep 17 00:00:00 2001 From: Zenithal Date: Thu, 24 Dec 2020 21:01:44 +0800 Subject: [PATCH 43/44] Add subsections on chained agent forwarding --- README.md | 39 +++++++++++++++++++++++++++++++++++---- 1 file changed, 35 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 1b2bef0..905162a 100644 --- a/README.md +++ b/README.md @@ -58,6 +58,7 @@ If you have a comment or suggestion, please open an [Issue](https://github.com/d * [Remote machines (SSH Agent Forwarding)](#remote-machines-ssh-agent-forwarding) - [Use ssh-agent](#use-ssh-agent) - [Use S.gpg-agent.ssh](#use-sgpg-agentssh) + - [Chained SSH Agent Forwarding](#chained-ssh-agent-forwarding) * [GitHub](#github) * [OpenBSD](#openbsd-1) * [Windows](#windows-1) @@ -68,6 +69,7 @@ If you have a comment or suggestion, please open an [Issue](https://github.com/d - [Remote host configuration](#remote-host-configuration) - [Remote Machines (GPG Agent Forwarding)](#remote-machines-gpg-agent-forwarding) * [Steps for older distributions](#steps-for-older-distributions) + * [Chained GPG Agent Forwarding](#chained-gpg-agent-forwarding) - [Using Multiple Keys](#using-multiple-keys) - [Require touch](#require-touch) - [Email](#email) @@ -2124,7 +2126,22 @@ After typing or sourcing your shell rc file, with `ssh-add -l` you should find y **Note** In this process no gpg-agent in the remote is involved, hence `gpg-agent.conf` in the remote is of no use. Also pinentry is invoked locally. -**Note** Agent forwarding may be chained through multiple hosts +### Chained SSH Agent Forwarding + +If you use `ssh-agent` provided by OpenSSH and want to forward it into a *third* box, you can just `ssh -A third` on the *remote*. + +Meanwhile, if you use `S.gpg-agent.ssh`, assume you have gone through the steps above and have `S.gpg-agent.ssh` on the *remote*, and you would like to forward this agent into a *third* box, first you may need to configure `sshd_config` and `SSH_AUTH_SOCK` of *third* in the same way as *remote*, then in the ssh config of *remote*, add the following lines + +```console +Host third + Hostname third-host.tld + StreamLocalBindUnlink yes + RemoteForward /run/user/1000/gnupg/S.gpg-agent.ssh /run/user/1000/gnupg/S.gpg-agent.ssh + # RemoteForward [remote socket] [local socket] + # Note that ForwardAgent is not wanted here! +``` + +You should change the path according to `gpgconf --list-dirs agent-ssh-socket` on *remote* and *third*. ## GitHub @@ -2267,7 +2284,7 @@ Log in to the remote host, you should have the pinentry dialog asking for the Yu On the remote host, type `ssh-add -l` - if you see the ssh key, that means forwarding works! -**Note** Agent forwarding may be chained through multiple hosts - just follow the same [protocol](#remote-host-configuration) to configure each host. +**Note** Agent forwarding may be chained through multiple hosts - just follow the same [protocol](#remote-host-configuration) to configure each host. You may also read this part on [chained ssh agent forwarding](#chained-ssh-agent-forwarding). # Remote Machines (GPG Agent Forwarding) @@ -2334,10 +2351,24 @@ extra-socket /run/user/1000/gnupg/S.gpg-agent.extra **Important** Any pinentry program except `pinentry-tty` or `pinentry-curses` may be used. This is because local `gpg-agent` may start headlessly (By systemd without `$GPG_TTY` set locally telling which tty it is on), thus failed to obtain the pin. Errors on the remote may be misleading saying that there is *IO Error* (Yes internally there is actually *IO Error* since it happens when writing to/reading from tty while finding no tty to use, but for end users this is not friendly). -**Note** Agent forwarding may be chained through multiple hosts - See [Issue #85](https://github.com/drduh/YubiKey-Guide/issues/85) for more information and troubleshooting. +## Chained GPG Agent Forwarding + +Assume you have gone through the steps above and have `S.gpg-agent` on the *remote*, and you would like to forward this agent into a *third* box, first you may need to configure `sshd_config` of *third* in the same way as *remote*, then in the ssh config of *remote*, add the following lines + +```console +Host third + Hostname third-host.tld + StreamLocalBindUnlink yes + RemoteForward /run/user/1000/gnupg/S.gpg-agent /run/user/1000/gnupg/S.gpg-agent + # RemoteForward [remote socket] [local socket] +``` + +You should change the path according to `gpgconf --list-dirs agent-socket` on *remote* and *third*. + +**Note** On *local* you have `S.gpg-agent.extra` whereas on *remote* and *third*, you only have `S.gpg-agent`. + # Using Multiple Keys To use a single identity with multiple YubiKeys - or to replace a lost card with another - issue this command to switch keys: From 1eacf97835fb7de951bc715205a94de16e1d496f Mon Sep 17 00:00:00 2001 From: Zenithal Date: Thu, 24 Dec 2020 21:08:41 +0800 Subject: [PATCH 44/44] Rephrase one sentence according to one comment on drduh/YubiKey-Guide#225 --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 905162a..a3977e8 100644 --- a/README.md +++ b/README.md @@ -2234,7 +2234,7 @@ The goal here is to make the SSH client inside WSL work together with the Window #### Use ssh-agent or use S.weasel-pegant -One way to forward is just `ssh -A` (still need to eval weasel to setup local ssh-agent), and only relies on OpenSSH. In this track, `ForwardAgent` and `AllowAgentForwarding` may be involved. Otherwise they are of no use or even harm the forwarding. See [SSH Agent Forwarding](#remote-machines-ssh-agent-forwarding) for more info. +One way to forward is just `ssh -A` (still need to eval weasel to setup local ssh-agent), and only relies on OpenSSH. In this track, `ForwardAgent` and `AllowAgentForwarding` in ssh/sshd config may be involved; However, if you use the other way(gpg ssh socket forwarding), you should not enable `ForwardAgent` in ssh config. See [SSH Agent Forwarding](#remote-machines-ssh-agent-forwarding) for more info. Another way is to forward the gpg ssh socket, as described below.