mirrors
/
YubiKey-Guide
mirror of https://github.com/drduh/YubiKey-Guide
0
0
Fork 0
Code Releases Activity

reset all changes

pull/282/head
apiraino 2022-04-12 16:04:34 +02:00
parent a725230d23
commit 813352d30a
No known key found for this signature in database
GPG Key ID: EE6A89440C49992C
1 changed files with 423 additions and 207 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

574
README.md
View File

@ -4,81 +4,81 @@ Keys stored on YubiKey are [non-exportable](https://support.yubico.com/support/s
**New!** [drduh/Purse](https://github.com/drduh/Purse) is a password manager which uses GPG and YubiKey. **New!** [drduh/Purse](https://github.com/drduh/Purse) is a password manager which uses GPG and YubiKey.
> **Security Note**: If you followed this guide before Jan 2021, your GPG _PIN_ and _Admin PIN_ may be set to their default values (`123456` and `12345678` respectively). This would allow an attacker to use your Yubikey or reset your PIN. Please see the [Change PIN](#change-pin) section for details on how to change your PINs. > **Security Note**: If you followed this guide before Jan 2021, your GPG *PIN* and *Admin PIN* may be set to their default values (`123456` and `12345678` respectively). This would allow an attacker to use your Yubikey or reset your PIN. Please see the [Change PIN](#change-pin) section for details on how to change your PINs.
If you have a comment or suggestion, please open an [Issue](https://github.com/drduh/YubiKey-Guide/issues) on GitHub. If you have a comment or suggestion, please open an [Issue](https://github.com/drduh/YubiKey-Guide/issues) on GitHub.
- [Purchase](#purchase) - [Purchase](#purchase)
- [Prepare environment](#prepare-environment) - [Prepare environment](#prepare-environment)
- [Required software](#required-software) - [Required software](#required-software)
- [Debian and Ubuntu](#debian-and-ubuntu) * [Debian and Ubuntu](#debian-and-ubuntu)
- [Arch](#arch) * [Arch](#arch)
- [RHEL7](#rhel7) * [RHEL7](#rhel7)
- [NixOS](#nixos) * [NixOS](#nixos)
- [OpenBSD](#openbsd) * [OpenBSD](#openbsd)
- [macOS](#macos) * [macOS](#macos)
- [Windows](#windows) * [Windows](#windows)
- [Entropy](#entropy) - [Entropy](#entropy)
- [Creating keys](#creating-keys) - [Creating keys](#creating-keys)
- [Temporary working directory](#temporary-working-directory) * [Temporary working directory](#temporary-working-directory)
- [Harden configuration](#harden-configuration) * [Harden configuration](#harden-configuration)
- [Master key](#master-key) - [Master key](#master-key)
- [Sign with existing key](#sign-with-existing-key) - [Sign with existing key](#sign-with-existing-key)
- [Sub-keys](#sub-keys) - [Sub-keys](#sub-keys)
- [Signing](#signing) * [Signing](#signing)
- [Encryption](#encryption) * [Encryption](#encryption)
- [Authentication](#authentication) * [Authentication](#authentication)
- [Add extra identities](#add-extra-identities) * [Add extra identities](#add-extra-identities)
- [Verify](#verify) - [Verify](#verify)
- [Export secret keys](#export-secret-keys) - [Export secret keys](#export-secret-keys)
- [Revocation certificate](#revocation-certificate) - [Revocation certificate](#revocation-certificate)
- [Backup](#backup) - [Backup](#backup)
- [Export public keys](#export-public-keys) - [Export public keys](#export-public-keys)
- [Configure Smartcard](#configure-smartcard) - [Configure Smartcard](#configure-smartcard)
- [Change PIN](#change-pin) * [Change PIN](#change-pin)
- [Enable KDF](#enable-kdf) * [Enable KDF](#enable-kdf)
- [Set information](#set-information) * [Set information](#set-information)
- [Transfer keys](#transfer-keys) - [Transfer keys](#transfer-keys)
- [Signing](#signing-1) * [Signing](#signing-1)
- [Encryption](#encryption-1) * [Encryption](#encryption-1)
- [Authentication](#authentication-1) * [Authentication](#authentication-1)
- [Verify card](#verify-card) - [Verify card](#verify-card)
- [Multiple YubiKeys](#multiple-yubikeys) - [Multiple YubiKeys](#multiple-yubikeys)
- [Cleanup](#cleanup) - [Cleanup](#cleanup)
- [Using keys](#using-keys) - [Using keys](#using-keys)
- [Rotating keys](#rotating-keys) - [Rotating keys](#rotating-keys)
- [Setup environment](#setup-environment) * [Setup environment](#setup-environment)
- [Renewing sub-keys](#renewing-sub-keys) * [Renewing sub-keys](#renewing-sub-keys)
- [Rotating keys](#rotating-keys-1) * [Rotating keys](#rotating-keys-1)
- [Adding notations](#adding-notations) - [Adding notations](#adding-notations)
- [SSH](#ssh) - [SSH](#ssh)
- [Create configuration](#create-configuration) * [Create configuration](#create-configuration)
- [Replace agents](#replace-agents) * [Replace agents](#replace-agents)
- [Copy public key](#copy-public-key) * [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) * [Connect with public key authentication](#connect-with-public-key-authentication)
- [Import SSH keys](#import-ssh-keys) * [Import SSH keys](#import-ssh-keys)
- [Remote machines (SSH Agent Forwarding)](#remote-machines-ssh-agent-forwarding) * [Remote machines (SSH Agent Forwarding)](#remote-machines-ssh-agent-forwarding)
- [Use ssh-agent](#use-ssh-agent) - [Use ssh-agent](#use-ssh-agent)
- [Use S.gpg-agent.ssh](#use-sgpg-agentssh) - [Use S.gpg-agent.ssh](#use-sgpg-agentssh)
- [Chained SSH Agent Forwarding](#chained-ssh-agent-forwarding) - [Chained SSH Agent Forwarding](#chained-ssh-agent-forwarding)
- [GitHub](#github) * [GitHub](#github)
- [OpenBSD](#openbsd-1) * [OpenBSD](#openbsd-1)
- [Windows](#windows-1) * [Windows](#windows-1)
- [WSL](#wsl) + [WSL](#wsl)
- [Use ssh-agent or use S.weasel-pegant](#use-ssh-agent-or-use-sweasel-pegant) - [Use ssh-agent or use S.weasel-pegant](#use-ssh-agent-or-use-sweasel-pegant)
- [Prerequisites](#prerequisites) - [Prerequisites](#prerequisites)
- [WSL configuration](#wsl-configuration) - [WSL configuration](#wsl-configuration)
- [Remote host configuration](#remote-host-configuration) - [Remote host configuration](#remote-host-configuration)
- [macOS](#macos-1) * [macOS](#macos-1)
- [Remote Machines (GPG Agent Forwarding)](#remote-machines-gpg-agent-forwarding) - [Remote Machines (GPG Agent Forwarding)](#remote-machines-gpg-agent-forwarding)
- [Steps for older distributions](#steps-for-older-distributions) * [Steps for older distributions](#steps-for-older-distributions)
- [Chained GPG Agent Forwarding](#chained-gpg-agent-forwarding) * [Chained GPG Agent Forwarding](#chained-gpg-agent-forwarding)
- [Using Multiple Keys](#using-multiple-keys) - [Using Multiple Keys](#using-multiple-keys)
- [Require touch](#require-touch) - [Require touch](#require-touch)
- [Email](#email) - [Email](#email)
- [Mailvelope on macOS](#mailvelope-on-macos) * [Mailvelope on macOS](#mailvelope-on-macos)
- [Mutt](#mutt) * [Mutt](#mutt)
- [Reset](#reset) - [Reset](#reset)
- [Recovery after reset](#recovery-after-reset) - [Recovery after reset](#recovery-after-reset)
- [Notes](#notes) - [Notes](#notes)
@ -86,11 +86,12 @@ If you have a comment or suggestion, please open an [Issue](https://github.com/d
- [Alternatives](#alternatives) - [Alternatives](#alternatives)
- [Links](#links) - [Links](#links)
# Purchase # Purchase
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/). Yubico have also just released a press release and blog post about supporting resident ssh keys on their Yubikeys including blue "security key 5 NFC" with OpenSSH 8.2 or later, see [here](https://www.yubico.com/blog/github-now-supports-ssh-security-keys/) for details. 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/). Yubico have also just released a press release and blog post about supporting resident ssh keys on their Yubikeys including blue "security key 5 NFC" with OpenSSH 8.2 or later, see [here](https://www.yubico.com/blog/github-now-supports-ssh-security-keys/) for details.
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. 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 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). 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).
@ -303,6 +304,7 @@ $ sudo cp -v installer/iso/*.iso /dev/sdb; sync
On NixOS, ensure that you have `pinentry-program /run/current-system/sw/bin/pinentry-curses` in your `$GNUPGHOME/gpg-agent.conf` before running any `gpg` commands. On NixOS, ensure that you have `pinentry-program /run/current-system/sw/bin/pinentry-curses` in your `$GNUPGHOME/gpg-agent.conf` before running any `gpg` commands.
## OpenBSD ## OpenBSD
```console ```console
@ -343,11 +345,9 @@ From YubiKey firmware version 5.2.3 onwards - which introduces "Enhancements to
## YubiKey ## YubiKey
To feed the system's PRNG with entropy generated by the YubiKey itself, issue: To feed the system's PRNG with entropy generated by the YubiKey itself, issue:
```console ```console
$ echo "SCD RANDOM 512" | gpg-connect-agent | sudo tee /dev/random | hexdump -C $ 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. This will seed the Linux kernel's PRNG with additional 512 bytes retrieved from the YubiKey.
## OneRNG ## OneRNG
@ -447,7 +447,7 @@ Disable networking for the remainder of the setup.
# Master key # Master key
The first key to be generated is the master key. It will be used for certification only when issuing sub-keys that are used for encryption, signing and authentication. The first key to generate is the master key. It will be used for certification only: to issue sub-keys that are used for encryption, signing and authentication.
**Important** The master key should be kept offline at all times and only accessed to revoke or issue new sub-keys. Keys can also be generated on the YubiKey itself to ensure no other copies exist. **Important** The master key should be kept offline at all times and only accessed to revoke or issue new sub-keys. Keys can also be generated on the YubiKey itself to ensure no other copies exist.
@ -471,38 +471,98 @@ BSSYMUGGTJQVWZZWOPJG
**Tip** 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`. **Tip** 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`.
Note: when creating the keys, we need to generate a lot of random bytes. It is a good idea to perform some other action (type on the keyboard, move the mouse, utilize the disks) during the prime generation; this gives the random number generator a better chance to gain enough entropy. Generate a new key with GPG, selecting `(8) RSA (set your own capabilities)`, `Certify` capability only and `4096` bit key size.
To remove some complexity from the process we will create the keys using a template and the `--batch` parameter. For futher details, full GNUPG documentation can be found at: https://www.gnupg.org/documentation/manuals/gnupg/Unattended-GPG-key-generation.html Do not set the master key to expire - see [Note #3](#notes).
For your convenience you can start from this RSA4096 key template: [gen-params-rsa4096](contrib/gen-params-rsa4096). If you're using GnuPG v2.1.7 or newer we strongly recommend generating ED25519 keys ([gen-params-ed25519](contrib/gen-params-ed25519), the procedure is the same). These templates will not set the master key to expire - see [Note #3](#notes).
Generate a RSA4096 master key:
```console ```console
$ gpg --batch --generate-key gen-params-rsa4096 $ gpg --expert --full-generate-key
gpg: Generating a basic OpenPGP key
gpg: key 0xEA5DE91459B80592 marked as ultimately trusted Please select what kind of key you want:
gpg: revocation certificate stored as '/tmp.FLZC0xcM/openpgp-revocs.d/D6F924841F78D62C65ABB9588B461860159FFB7B.rev' (1) RSA and RSA (default)
gpg: done (2) DSA and Elgamal
(3) DSA (sign only)
(4) RSA (sign only)
(7) DSA (set your own capabilities)
(8) RSA (set your own capabilities)
(9) ECC and ECC
(10) ECC (sign only)
(11) ECC (set your own capabilities)
(13) Existing key
Your selection? 8
Possible actions for a RSA key: Sign Certify Encrypt Authenticate
Current allowed actions: Sign Certify Encrypt
(S) Toggle the sign capability
(E) Toggle the encrypt capability
(A) Toggle the authenticate capability
(Q) Finished
Your selection? E
Possible actions for a RSA key: Sign Certify Encrypt Authenticate
Current allowed actions: Sign Certify
(S) Toggle the sign capability
(E) Toggle the encrypt capability
(A) Toggle the authenticate capability
(Q) Finished
Your selection? S
Possible actions for a RSA key: Sign Certify Encrypt Authenticate
Current allowed actions: Certify
(S) Toggle the sign capability
(E) Toggle the encrypt capability
(A) Toggle the authenticate capability
(Q) Finished
Your selection? Q
RSA keys may be between 1024 and 4096 bits long.
What keysize do you want? (2048) 4096
Requested keysize is 4096 bits
Please specify how long the key should be valid.
0 = key does not expire
<n> = key expires in n days
<n>w = key expires in n weeks
<n>m = key expires in n months
<n>y = key expires in n years
Key is valid for? (0) 0
Key does not expire at all
Is this correct? (y/N) y
``` ```
Let's check the result: Input any name and email address:
```console ```console
$ gpg --list-key GnuPG needs to construct a user ID to identify your key.
gpg: checking the trustdb
gpg: marginals needed: 3 completes needed: 1 trust model: pgp Real name: Dr Duh
gpg: depth: 0 valid: 1 signed: 0 trust: 0-, 0q, 0n, 0m, 0f, 1u Email address: doc@duh.to
/tmp.FLZC0xcM/pubring.kbx Comment: [Optional - leave blank]
------------------------------- You selected this USER-ID:
pub rsa4096/0xFF3E7D88647EBCDB 2021-08-22 [C] "Dr Duh <doc@duh.to>"
Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? o
We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilize the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
gpg: /tmp.FLZC0xcM/trustdb.gpg: trustdb created
gpg: key 0xFF3E7D88647EBCDB marked as ultimately trusted
gpg: directory '/tmp.FLZC0xcM/openpgp-revocs.d' created
gpg: revocation certificate stored as '/tmp.FLZC0xcM/openpgp-revocs.d/011CE16BD45B27A55BA8776DFF3E7D88647EBCDB.rev'
public and secret key created and signed.
pub rsa4096/0xFF3E7D88647EBCDB 2017-10-09 [C]
Key fingerprint = 011C E16B D45B 27A5 5BA8 776D FF3E 7D88 647E BCDB Key fingerprint = 011C E16B D45B 27A5 5BA8 776D FF3E 7D88 647E BCDB
uid [ultimate] Dr Duh <doc@duh.to> uid Dr Duh <doc@duh.to>
``` ```
The key fingerprint (`011C E16B D45B 27A5 5BA8 776D FF3E 7D88 647E BCDB`) will be used to create the three subkeys for signing, authentication and encryption.
Export the key ID as a [variable](https://stackoverflow.com/questions/1158091/defining-a-variable-with-or-without-export/1158231#1158231) (`KEYID`) for use later: Export the key ID as a [variable](https://stackoverflow.com/questions/1158091/defining-a-variable-with-or-without-export/1158231#1158231) (`KEYID`) for use later:
```console ```console
@ -527,61 +587,214 @@ $ gpg --default-key $OLDKEY --sign-key $KEYID
# Sub-keys # Sub-keys
Now create the three subkeys for signing, authentication and encryption. Use a 1 year expiration for sub-keys - they can be renewed using the offline master key. See [rotating keys](#rotating-keys). Edit the master key to add sub-keys:
We will use the the quick key manipulation interface of GNUPG (with `--quick-add-key`). See [the documentation](https://www.gnupg.org/documentation/manuals/gnupg/Unattended-GPG-key-generation.html#Unattended-GPG-key-generation).
Create a [signing subkey](https://stackoverflow.com/questions/5421107/can-rsa-be-both-used-as-encryption-and-signature/5432623#5432623):
```console ```console
$ gpg --quick-add-key "011C E16B D45B 27A5 5BA8 776D FF3E 7D88 647E BCDB" \ $ gpg --expert --edit-key $KEYID
rsa4096 sign 1y
Secret key is available.
sec rsa4096/0xEA5DE91459B80592
created: 2017-10-09 expires: never usage: C
trust: ultimate validity: ultimate
[ultimate] (1). Dr Duh <doc@duh.to>
``` ```
Now create an [encryption subkey](https://www.cs.cornell.edu/courses/cs5430/2015sp/notes/rsa_sign_vs_dec.php): Use 4096-bit RSA keys.
Use a 1 year expiration for sub-keys - they can be renewed using the offline master key. See [rotating keys](#rotating-keys).
## Signing
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 ```console
$ gpg --quick-add-key "011C E16B D45B 27A5 5BA8 776D FF3E 7D88 647E BCDB" \ gpg> addkey
rsa4096 encrypt 1y Key is protected.
You need a passphrase to unlock the secret key for
user: "Dr Duh <doc@duh.to>"
4096-bit RSA key, ID 0xFF3E7D88647EBCDB, created 2016-05-24
Please select what kind of key you want:
(3) DSA (sign only)
(4) RSA (sign only)
(5) Elgamal (encrypt only)
(6) RSA (encrypt only)
(7) DSA (set your own capabilities)
(8) RSA (set your own capabilities)
Your selection? 4
RSA keys may be between 1024 and 4096 bits long.
What keysize do you want? (2048) 4096
Requested keysize is 4096 bits
Please specify how long the key should be valid.
0 = key does not expire
<n> = key expires in n days
<n>w = key expires in n weeks
<n>m = key expires in n months
<n>y = key expires in n years
Key is valid for? (0) 1y
Key expires at Mon 10 Sep 2018 00:00:00 PM UTC
Is this correct? (y/N) y
Really create? (y/N) y
We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilize the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
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
[ultimate] (1). Dr Duh <doc@duh.to>
``` ```
Finally, create an [authentication subkey](https://superuser.com/questions/390265/what-is-a-gpg-with-authenticate-capability-used-for): ## Encryption
Next, create an [encryption key](https://www.cs.cornell.edu/courses/cs5430/2015sp/notes/rsa_sign_vs_dec.php) by selecting `(6) RSA (encrypt only)`:
```console ```console
$ gpg --quick-add-key "011C E16B D45B 27A5 5BA8 776D FF3E 7D88 647E BCDB" \ gpg> addkey
rsa4096 auth 1y Please select what kind of key you want:
(3) DSA (sign only)
(4) RSA (sign only)
(5) Elgamal (encrypt only)
(6) RSA (encrypt only)
(7) DSA (set your own capabilities)
(8) RSA (set your own capabilities)
(10) ECC (sign only)
(11) ECC (set your own capabilities)
(12) ECC (encrypt only)
(13) Existing key
Your selection? 6
RSA keys may be between 1024 and 4096 bits long.
What keysize do you want? (2048) 4096
Requested keysize is 4096 bits
Please specify how long the key should be valid.
0 = key does not expire
<n> = key expires in n days
<n>w = key expires in n weeks
<n>m = key expires in n months
<n>y = key expires in n years
Key is valid for? (0) 1y
Key expires at Mon 10 Sep 2018 00:00:00 PM UTC
Is this correct? (y/N) y
Really create? (y/N) y
We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilize the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
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
[ultimate] (1). Dr Duh <doc@duh.to>
``` ```
Let's check the final result: ## Authentication
Finally, create an [authentication key](https://superuser.com/questions/390265/what-is-a-gpg-with-authenticate-capability-used-for).
GPG doesn't provide an authenticate-only key type, so select `(8) RSA (set your own capabilities)` and toggle the required capabilities until the only allowed action is `Authenticate`:
```console ```console
$ gpg --list-keys gpg> addkey
/tmp.FLZC0xcM/pubring.kbx Please select what kind of key you want:
------------------------------- (3) DSA (sign only)
pub rsa4096/0xFF3E7D88647EBCDB 2021-08-22 [C] (4) RSA (sign only)
Key fingerprint = 011C E16B D45B 27A5 5BA8 776D FF3E 7D88 647E BCDB (5) Elgamal (encrypt only)
uid [ultimate] Dr Duh <doc@duh.to> (6) RSA (encrypt only)
sub rsa4096/0xBECFA3C1AE191D15 2017-10-09 [S] [expires: 2018-10-09] (7) DSA (set your own capabilities)
sub rsa4096/0x5912A795E90DD2CF 2017-10-09 [E] [expires: 2018-10-09] (8) RSA (set your own capabilities)
sub rsa4096/0x3F29127E79649A3D 2017-10-09 [A] [expires: 2018-10-09] (10) ECC (sign only)
(11) ECC (set your own capabilities)
(12) ECC (encrypt only)
(13) Existing key
Your selection? 8
Possible actions for a RSA key: Sign Encrypt Authenticate
Current allowed actions: Sign Encrypt
(S) Toggle the sign capability
(E) Toggle the encrypt capability
(A) Toggle the authenticate capability
(Q) Finished
Your selection? S
Possible actions for a RSA key: Sign Encrypt Authenticate
Current allowed actions: Encrypt
(S) Toggle the sign capability
(E) Toggle the encrypt capability
(A) Toggle the authenticate capability
(Q) Finished
Your selection? E
Possible actions for a RSA key: Sign Encrypt Authenticate
Current allowed actions:
(S) Toggle the sign capability
(E) Toggle the encrypt capability
(A) Toggle the authenticate capability
(Q) Finished
Your selection? A
Possible actions for a RSA key: Sign Encrypt Authenticate
Current allowed actions: Authenticate
(S) Toggle the sign capability
(E) Toggle the encrypt capability
(A) Toggle the authenticate capability
(Q) Finished
Your selection? Q
RSA keys may be between 1024 and 4096 bits long.
What keysize do you want? (2048) 4096
Requested keysize is 4096 bits
Please specify how long the key should be valid.
0 = key does not expire
<n> = key expires in n days
<n>w = key expires in n weeks
<n>m = key expires in n months
<n>y = key expires in n years
Key is valid for? (0) 1y
Key expires at Mon 10 Sep 2018 00:00:00 PM UTC
Is this correct? (y/N) y
Really create? (y/N) y
We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilize the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
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 <doc@duh.to>
``` ```
If you want to add an extra UID, open the keyring: Finish by saving the keys.
````console
-gpg> save
```console
gpg> save
```
## Add extra identities ## Add extra identities
(Optional) To add additional email addresses or identities, use `adduid`. (Optional) To add additional email addresses or identities, use `adduid`:
First open the keyring:
```console
$ gpg --expert --edit-key $KEYID
````
Then add the new identity:
```console ```console
gpg> adduid gpg> adduid
@ -726,11 +939,11 @@ $ gpg -o \path\to\dir\sub.gpg --armor --export-secret-subkeys $KEYID
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. 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 reasonable to assume this _will_ occur at some point and the only remaining way to deprecate orphaned keys is a revocation 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.
To create the revocation certificate: To create the revocation certificate:
```console ``` console
$ gpg --output $GNUPGHOME/revoke.asc --gen-revoke $KEYID $ gpg --output $GNUPGHOME/revoke.asc --gen-revoke $KEYID
``` ```
@ -739,9 +952,10 @@ The `revoke.asc` certificate file should be stored (or printed) in a (secondary)
# Backup # Backup
Once keys are moved to YubiKey, they cannot be moved again! Create an **encrypted** backup of the keyring on removable media so you can keep it offline in a safe place. Once keys are moved to YubiKey, they cannot be moved again! Create an **encrypted** backup of the keyring on removable media so you can keep it offline in a safe place.
**Tip** The ext2 filesystem (without encryption) can be mounted on both Linux and OpenBSD. Consider using a FAT32/NTFS filesystem for MacOS/Windows compatibility instead. **Tip** The ext2 filesystem (without encryption) can be mounted on both Linux and OpenBSD. Consider using a FAT32/NTFS filesystem for MacOS/Windows compatibility instead.
As an additional backup measure, consider using a [paper copy](https://www.jabberwocky.com/software/paperkey/) of the keys. The [Linux Kernel Maintainer PGP Guide](https://www.kernel.org/doc/html/latest/process/maintainer-pgp-guide.html#back-up-your-master-key-for-disaster-recovery) points out that such printouts _are still password-protected_. It recommends to _write the password on the paper_, since it will be unlikely that you remember the original key password that was used when the paper backup was created. Obviously, you need a really good place to keep such a printout. As an additional backup measure, consider using a [paper copy](https://www.jabberwocky.com/software/paperkey/) of the keys. The [Linux Kernel Maintainer PGP Guide](https://www.kernel.org/doc/html/latest/process/maintainer-pgp-guide.html#back-up-your-master-key-for-disaster-recovery) points out that such printouts *are still password-protected*. It recommends to *write the password on the paper*, since it will be unlikely that you remember the original key password that was used when the paper backup was created. Obviously, you need a really good place to keep such a printout.
**Linux** **Linux**
@ -873,6 +1087,7 @@ $ sudo umount /mnt/encrypted-storage/
$ sudo cryptsetup luksClose secret $ sudo cryptsetup luksClose secret
``` ```
**OpenBSD** **OpenBSD**
Attach a USB disk and determine its label: Attach a USB disk and determine its label:
@ -959,7 +1174,7 @@ See [OpenBSD FAQ#14](https://www.openbsd.org/faq/faq14.html#softraidCrypto) for
# Export public keys # 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. **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. Create another partition on the removable storage device to store the public key, or reconnect networking and upload to a key server.
@ -1079,7 +1294,6 @@ General key info..: [none]
Use the [YubiKey Manager](https://developers.yubico.com/yubikey-manager) application (note, this is not the similarly named older YubiKey NEO Manager) to enable CCID functionality. Use the [YubiKey Manager](https://developers.yubico.com/yubikey-manager) application (note, this is not the similarly named older YubiKey NEO Manager) to enable CCID functionality.
## Enable KDF ## Enable KDF
Key Derived Function (KDF) enables YubiKey to store the hash of PIN, preventing the PIN from being passed as plain text. Note that this requires a relatively new version of GnuPG to work, and may not be compatible with other GPG clients (notably mobile clients). These incompatible clients will be unable to use the YubiKey GPG functions as the PIN will always be rejected. If you are not sure you will only be using your YubiKey on supported platforms, it may be better to skip this step. Key Derived Function (KDF) enables YubiKey to store the hash of PIN, preventing the PIN from being passed as plain text. Note that this requires a relatively new version of GnuPG to work, and may not be compatible with other GPG clients (notably mobile clients). These incompatible clients will be unable to use the YubiKey GPG functions as the PIN will always be rejected. If you are not sure you will only be using your YubiKey on supported platforms, it may be better to skip this step.
```console ```console
@ -1091,19 +1305,19 @@ gpg/card> kdf-setup
## Change PIN ## Change PIN
The [GPG interface](https://developers.yubico.com/PGP/) is separate from other modules on a Yubikey such as the [PIV interface](https://developers.yubico.com/PIV/Introduction/YubiKey_and_PIV.html). The GPG interface has its own _PIN_, _Admin PIN_, and _Reset Code_ - these should be changed from default values! The [GPG interface](https://developers.yubico.com/PGP/) is separate from other modules on a Yubikey such as the [PIV interface](https://developers.yubico.com/PIV/Introduction/YubiKey_and_PIV.html). The GPG interface has its own *PIN*, *Admin PIN*, and *Reset Code* - these should be changed from default values!
Entering the user _PIN_ incorrectly three times will cause the PIN to become blocked; it can be unblocked with either the _Admin PIN_ or _Reset Code_. Entering the user *PIN* incorrectly three times will cause the PIN to become blocked; it can be unblocked with either the *Admin PIN* or *Reset Code*.
Entering the _Admin PIN_ or _Reset Code_ incorrectly three times destroys all GPG data on the card. The Yubikey will have to be reconfigured. Entering the *Admin PIN* or *Reset Code* incorrectly three times destroys all GPG data on the card. The Yubikey will have to be reconfigured.
| Name | Default Value | Use | Name | Default Value | Use
| ---------- | ------------- | ------------------------------------------------------------------------------------------ | -----------|---------------|-------------------------------------------------------------
| PIN | `123456` | decrypt and authenticate (SSH) | PIN | `123456` | decrypt and authenticate (SSH)
| Admin PIN | `12345678` | reset _PIN_, change _Reset Code_, add keys and owner information | Admin PIN | `12345678` | reset *PIN*, change *Reset Code*, add keys and owner information
| Reset code | _**None**_ | reset _PIN_ ([more information](https://forum.yubico.com/viewtopicd01c.html?p=9055#p9055)) | Reset code | _**None**_ | reset *PIN* ([more information](https://forum.yubico.com/viewtopicd01c.html?p=9055#p9055))
Values are valid up to 127 ASCII characters and must be at least 6 (_PIN_) or 8 (_Admin PIN_, _Reset Code_) characters. See the GnuPG documentation on [Managing PINs](https://www.gnupg.org/howtos/card-howto/en/ch03s02.html) for details. Values are valid up to 127 ASCII characters and must be at least 6 (*PIN*) or 8 (*Admin PIN*, *Reset Code*) characters. See the GnuPG documentation on [Managing PINs](https://www.gnupg.org/howtos/card-howto/en/ch03s02.html) for details.
To update the GPG PINs on the Yubikey: To update the GPG PINs on the Yubikey:
@ -1331,34 +1545,39 @@ $ cd $GNUPGHOME
## Switching between two or more Yubikeys. ## Switching between two or more Yubikeys.
When you add a GPG key to a Yubikey using the _keytocard_ command, GPG deletes the key from your keyring and adds a _stub_ pointing to that exact Yubikey (the stub identifies the GPG KeyID and the Yubikey's serial number). When you add a GPG key to a Yubikey using the *keytocard* command, GPG deletes the key from your keyring and adds a *stub* pointing to that exact Yubikey (the stub identifies the GPG KeyID and the Yubikey's serial number).
However, when you do this same operation for a second Yubikey, the stub in your keyring is overwritten by the _keytocard_ operation and now the stub points to your second Yubikey. Adding more repeats this overwriting operation.
However, when you do this same operation for a second Yubikey, the stub in your keyring is overwritten by the *keytocard* operation and now the stub points to your second Yubikey. Adding more repeats this overwriting operation.
In other words, the stub will point ONLY to the LAST Yubikey written to. In other words, the stub will point ONLY to the LAST Yubikey written to.
When using GPG key operations with the GPG key you placed onto the Yubikeys, GPG will request a specific Yubikey asking that you insert a Yubikey with a given serial number (referenced by the stub). GPG will not recognise another Yubikey with a different serial number without manual intervention. When using GPG key operations with the GPG key you placed onto the Yubikeys, GPG will request a specific Yubikey asking that you insert a Yubikey with a given serial number (referenced by the stub). GPG will not recognise another Yubikey with a different serial number without manual intervention.
You can force GPG to scan the card and re-create the stubs to point to another Yubikey. You can force GPG to scan the card and re-create the stubs to point to another Yubikey.
Having created two (or more Yubikeys) with the same GPG key (as described above) where the stubs are pointing to the second Yubikey: Having created two (or more Yubikeys) with the same GPG key (as described above) where the stubs are pointing to the second Yubikey:
Insert the first Yubikey (which has a different serial number) and run the following command: Insert the first Yubikey (which has a different serial number) and run the following command:
```console ```console
$ gpg-connect-agent "scd serialno" "learn --force" /bye $ gpg-connect-agent "scd serialno" "learn --force" /bye
``` ```
GPG will then scan your first Yubikey for GPG keys and recreate the stubs to point to the GPG keyID and Yubikey Serial number of this first Yubikey. GPG will then scan your first Yubikey for GPG keys and recreate the stubs to point to the GPG keyID and Yubikey Serial number of this first Yubikey.
To return to using the second Yubikey just repeat (insert other Yubikey and re-run command). To return to using the second Yubikey just repeat (insert other Yubikey and re-run command).
Obviously this command is not easy to remember so it is recommended to either create a script or a shell alias to make this more user friendly. Obviously this command is not easy to remember so it is recommended to either create a script or a shell alias to make this more user friendly.
# Cleanup # Cleanup
Ensure you have: Ensure you have:
- Saved encryption, signing and authentication sub-keys to YubiKey (`gpg -K` should show `ssb>` for sub-keys). * 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 YubiKey user and admin PINs which you changed from defaults.
- Saved the password to the GPG master key in a _permanent_ location. * Saved the password to the GPG master key in a *permanent* location.
- Saved a copy of the master key, sub-keys and revocation certificate on an encrypted volume, to be stored offline. * 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 the password to that encrypted volume in a separate location.
- Saved a copy of the public key somewhere easily accessible later. * Saved a copy of the public key somewhere easily accessible later.
Reboot or [securely delete](http://srm.sourceforge.net/) `$GNUPGHOME` and remove the secret keys from the GPG keyring: Reboot or [securely delete](http://srm.sourceforge.net/) `$GNUPGHOME` and remove the secret keys from the GPG keyring:
@ -1696,7 +1915,6 @@ Please specify how long the key should be valid.
<n>y = key expires in n years <n>y = key expires in n years
Key is valid for? (0) Key is valid for? (0)
``` ```
Follow these prompts to set a new expiration date, then `save` to save your changes. Follow these prompts to set a new expiration date, then `save` to save your changes.
Next, export the public key: Next, export the public key:
@ -1768,7 +1986,7 @@ Adding notations requires access to the master key so we can follow the setup in
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. 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" in 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: At this point the public key can be exported:
@ -1839,16 +2057,15 @@ gpgconf --launch gpg-agent
``` ```
If you use fish, the correct lines for your `config.fish` would look like this (consider putting them into the `is-interactive` block depending on your use case): If you use fish, the correct lines for your `config.fish` would look like this (consider putting them into the `is-interactive` block depending on your use case):
```fish ```fish
set -x GPG_TTY (tty) set -x GPG_TTY (tty)
set -x SSH_AUTH_SOCK (gpgconf --list-dirs agent-ssh-socket) set -x SSH_AUTH_SOCK (gpgconf --list-dirs agent-ssh-socket)
gpgconf --launch gpg-agent 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 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. 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 ## Copy public key
@ -1980,7 +2197,7 @@ Host
After successfully ssh into the remote, you should check that you have `/run/user/1000/gnupg/S.gpg-agent.ssh` lying there. After successfully ssh into the remote, you should check that you have `/run/user/1000/gnupg/S.gpg-agent.ssh` lying there.
Then in the _remote_ you can type in command line or configure in the shell rc file with: Then in the *remote* you can type in command line or configure in the shell rc file with:
```console ```console
export SSH_AUTH_SOCK="/run/user/$UID/gnupg/S.gpg-agent.ssh" export SSH_AUTH_SOCK="/run/user/$UID/gnupg/S.gpg-agent.ssh"
@ -1992,9 +2209,9 @@ After typing or sourcing your shell rc file, with `ssh-add -l` you should find y
### Chained SSH Agent Forwarding ### 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_. 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 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 ```console
Host third Host third
@ -2005,7 +2222,7 @@ Host third
# Note that ForwardAgent is not wanted here! # Note that ForwardAgent is not wanted here!
``` ```
You should change the path according to `gpgconf --list-dirs agent-ssh-socket` on _remote_ and _third_. You should change the path according to `gpgconf --list-dirs agent-ssh-socket` on *remote* and *third*.
## GitHub ## GitHub
@ -2050,38 +2267,38 @@ $ doas reboot
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 your device's full name, plug in your YubiKey and open PowerShell to run the following command: 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 your device's full name, plug in your YubiKey and open PowerShell to run the following command:
```powershell ``` powershell
PS C:\WINDOWS\system32> Get-PnpDevice -Class SoftwareDevice | Where-Object {$_.FriendlyName -like "*YubiKey*"} | Select-Object -ExpandProperty FriendlyName PS C:\WINDOWS\system32> Get-PnpDevice -Class SoftwareDevice | Where-Object {$_.FriendlyName -like "*YubiKey*"} | Select-Object -ExpandProperty FriendlyName
Yubico YubiKey OTP+FIDO+CCID 0 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. 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: * Create or edit `%APPDATA%/gnupg/scdaemon.conf` to add:
``` ```
reader-port <your yubikey device's full name, e.g. Yubico YubiKey OTP+FIDO+CCID 0> reader-port <your yubikey device's full name, e.g. Yubico YubiKey OTP+FIDO+CCID 0>
``` ```
- Create or edit `%APPDATA%/gnupg/gpg-agent.conf` to add: * Create or edit `%APPDATA%/gnupg/gpg-agent.conf` to add:
``` ```
enable-ssh-support enable-ssh-support
enable-putty-support enable-putty-support
``` ```
- Open a command console, restart the agent: * Open a command console, restart the agent:
``` ```
> gpg-connect-agent killagent /bye > gpg-connect-agent killagent /bye
> gpg-connect-agent /bye > gpg-connect-agent /bye
``` ```
- Enter `> gpg --card-status` to see YubiKey details. * Enter `> gpg --card-status` to see YubiKey details.
- Import the [public key](#export-public-key): `> gpg --import <path to public key file>` * Import the [public key](#export-public-key): `> gpg --import <path to public key file>`
- [Trust the master key](#trust-master-key) * [Trust the master key](#trust-master-key)
- Retrieve the public key id: `> gpg --list-public-keys` * Retrieve the public key id: `> gpg --list-public-keys`
- Export the SSH key from GPG: `> gpg --export-ssh-key <public key id>` * Export the SSH key from GPG: `> gpg --export-ssh-key <public key id>`
Copy this key to a file for later use. It represents the public SSH key corresponding to the secret key on the YubiKey. You can upload this key to any server you wish to SSH into. Copy this key to a file for later use. It represents the public SSH key corresponding to the secret key on the YubiKey. You can upload this key to any server you wish to SSH into.
@ -2104,9 +2321,9 @@ Another way is to forward the gpg ssh socket, as described below.
#### Prerequisites #### Prerequisites
- Ubuntu 16.04 or newer for WSL * Ubuntu 16.04 or newer for WSL
- Kleopatra * Kleopatra
- [Windows configuration](#windows) * [Windows configuration](#windows)
#### WSL configuration #### WSL configuration
@ -2218,7 +2435,7 @@ To do this, you need access to the remote machine and the YubiKey has to be set
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. 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. **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` On the remote machine, edit `/etc/ssh/sshd_config` to set `StreamLocalBindUnlink yes`
@ -2262,22 +2479,22 @@ Host
# RemoteForward [remote socket] [local socket] # 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: 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 pinentry-program /usr/bin/pinentry-gtk-2
extra-socket /run/user/1000/gnupg/S.gpg-agent.extra 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 the local machine. **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 the 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 an _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.) **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 an *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. See [Issue #85](https://github.com/drduh/YubiKey-Guide/issues/85) for more information and troubleshooting.
## Chained GPG Agent Forwarding ## 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: 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 ```console
Host third Host third
@ -2287,9 +2504,9 @@ Host third
# RemoteForward [remote socket] [local socket] # RemoteForward [remote socket] [local socket]
``` ```
You should change the path according to `gpgconf --list-dirs agent-socket` on _remote_ and _third_. 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`. **Note** On *local* you have `S.gpg-agent.extra` whereas on *remote* and *third*, you only have `S.gpg-agent`.
# Using Multiple Keys # Using Multiple Keys
@ -2407,7 +2624,9 @@ To allow Chrome to run gpgme, edit `~/Library/Application\ Support/Google/Chrome
"description": "Integration with GnuPG", "description": "Integration with GnuPG",
"path": "/usr/local/bin/gpgme-json", "path": "/usr/local/bin/gpgme-json",
"type": "stdio", "type": "stdio",
"allowed_origins": ["chrome-extension://kajibbejlbohfaggdiogboambcijhkke/"] "allowed_origins": [
"chrome-extension://kajibbejlbohfaggdiogboambcijhkke/"
]
} }
``` ```
@ -2469,7 +2688,7 @@ Before you unmount your backup, ask yourself if you should make another one just
# Notes # 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). 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).
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. 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. 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 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.
@ -2512,19 +2731,16 @@ Before you unmount your backup, ask yourself if you should make another one just
- 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, `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`. - 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, when you try the above `--edit-key` command, you get the error - If, when you try the above `--edit-key` command, you get the error
`Need the secret key to do this.`, you can manually specify trust for the key in `Need the secret key to do this.`, you can manually specify trust for the key in
`~/.gnupg/gpg.conf` by using the `trust-key [your key ID]` directive. `~/.gnupg/gpg.conf` by using the `trust-key [your key ID]` directive.
- If, when using a previously provisioned YubiKey on a new computer with `pass`, you see the - If, when using a previously provisioned YubiKey on a new computer with `pass`, you see the
following error on `pass insert`: following error on `pass insert`:
``` ```
gpg: 0x0000000000000000: There is no assurance this key belongs to the named user gpg: 0x0000000000000000: There is no assurance this key belongs to the named user
gpg: [stdin]: encryption failed: Unusable public key gpg: [stdin]: encryption failed: Unusable public key
``` ```
you need to adjust the trust associated with the key. See the above bullet. you need to adjust the trust associated with the key. See the above bullet.
- If you receive the error, `gpg: 0x0000000000000000: skipped: Unusable public key`, `signing failed: Unusable secret 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. - If you receive the error, `gpg: 0x0000000000000000: skipped: Unusable public key`, `signing failed: Unusable secret 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.
@ -2533,29 +2749,29 @@ Before you unmount your backup, ask yourself if you should make another one just
# Alternatives # Alternatives
_TODO: Information about other ways to authenticate SSH (e.g., without GPG) and other YubiKey features_ *TODO: Information about other ways to authenticate SSH (e.g., without GPG) and other YubiKey features*
# Links # Links
- https://alexcabal.com/creating-the-perfect-gpg-keypair/ * https://alexcabal.com/creating-the-perfect-gpg-keypair/
- https://blog.habets.se/2013/02/GPG-and-SSH-with-Yubikey-NEO * https://blog.habets.se/2013/02/GPG-and-SSH-with-Yubikey-NEO
- https://blog.josefsson.org/2014/06/23/offline-gnupg-master-key-and-subkeys-on-yubikey-neo-smartcard/ * https://blog.josefsson.org/2014/06/23/offline-gnupg-master-key-and-subkeys-on-yubikey-neo-smartcard/
- https://blog.onefellow.com/post/180065697833/yubikey-forwarding-ssh-keys * https://blog.onefellow.com/post/180065697833/yubikey-forwarding-ssh-keys
- https://developers.yubico.com/PGP/ * https://developers.yubico.com/PGP/
- https://developers.yubico.com/PGP/Card_edit.html * https://developers.yubico.com/PGP/Card_edit.html
- https://developers.yubico.com/yubikey-personalization/ * https://developers.yubico.com/yubikey-personalization/
- https://evilmartians.com/chronicles/stick-with-security-yubikey-ssh-gnupg-macos * https://evilmartians.com/chronicles/stick-with-security-yubikey-ssh-gnupg-macos
- https://gist.github.com/ageis/14adc308087859e199912b4c79c4aaa4 * https://gist.github.com/ageis/14adc308087859e199912b4c79c4aaa4
- https://github.com/herlo/ssh-gpg-smartcard-config * https://github.com/herlo/ssh-gpg-smartcard-config
- https://github.com/tomlowenthal/documentation/blob/master/gpg/smartcard-keygen.md * https://github.com/tomlowenthal/documentation/blob/master/gpg/smartcard-keygen.md
- https://help.riseup.net/en/security/message-security/openpgp/best-practices * https://help.riseup.net/en/security/message-security/openpgp/best-practices
- https://jclement.ca/articles/2015/gpg-smartcard/ * https://jclement.ca/articles/2015/gpg-smartcard/
- https://rnorth.org/gpg-and-ssh-with-yubikey-for-mac * https://rnorth.org/gpg-and-ssh-with-yubikey-for-mac
- https://trmm.net/Yubikey * https://trmm.net/Yubikey
- https://www.bootc.net/archives/2013/06/09/my-perfect-gnupg-ssh-agent-setup/ * https://www.bootc.net/archives/2013/06/09/my-perfect-gnupg-ssh-agent-setup/
- https://www.esev.com/blog/post/2015-01-pgp-ssh-key-on-yubikey-neo/ * https://www.esev.com/blog/post/2015-01-pgp-ssh-key-on-yubikey-neo/
- https://www.hanselman.com/blog/HowToSetupSignedGitCommitsWithAYubiKeyNEOAndGPGAndKeybaseOnWindows.aspx * https://www.hanselman.com/blog/HowToSetupSignedGitCommitsWithAYubiKeyNEOAndGPGAndKeybaseOnWindows.aspx
- https://www.void.gr/kargig/blog/2013/12/02/creating-a-new-gpg-key-with-subkeys/ * https://www.void.gr/kargig/blog/2013/12/02/creating-a-new-gpg-key-with-subkeys/
- https://mlohr.com/gpg-agent-forwarding/ * https://mlohr.com/gpg-agent-forwarding/
- https://www.ingby.com/?p=293 * https://www.ingby.com/?p=293
- https://support.yubico.com/support/solutions/articles/15000027139-yubikey-5-2-3-enhancements-to-openpgp-3-4-support * https://support.yubico.com/support/solutions/articles/15000027139-yubikey-5-2-3-enhancements-to-openpgp-3-4-support