mirror of
https://github.com/drduh/YubiKey-Guide.git
synced 2024-11-18 02:05:11 +00:00
reset all changes
This commit is contained in:
apiraino
parent
a725230d23
commit
813352d30a
630
README.md
630
README.md
@ -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.
|
||||
|
||||
> **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.
|
||||
|
||||
- [Purchase](#purchase)
|
||||
- [Prepare environment](#prepare-environment)
|
||||
- [Required software](#required-software)
|
||||
- [Debian and Ubuntu](#debian-and-ubuntu)
|
||||
- [Arch](#arch)
|
||||
- [RHEL7](#rhel7)
|
||||
- [NixOS](#nixos)
|
||||
- [OpenBSD](#openbsd)
|
||||
- [macOS](#macos)
|
||||
- [Windows](#windows)
|
||||
* [Debian and Ubuntu](#debian-and-ubuntu)
|
||||
* [Arch](#arch)
|
||||
* [RHEL7](#rhel7)
|
||||
* [NixOS](#nixos)
|
||||
* [OpenBSD](#openbsd)
|
||||
* [macOS](#macos)
|
||||
* [Windows](#windows)
|
||||
- [Entropy](#entropy)
|
||||
- [Creating keys](#creating-keys)
|
||||
- [Temporary working directory](#temporary-working-directory)
|
||||
- [Harden configuration](#harden-configuration)
|
||||
* [Temporary working directory](#temporary-working-directory)
|
||||
* [Harden configuration](#harden-configuration)
|
||||
- [Master key](#master-key)
|
||||
- [Sign with existing key](#sign-with-existing-key)
|
||||
- [Sub-keys](#sub-keys)
|
||||
- [Signing](#signing)
|
||||
- [Encryption](#encryption)
|
||||
- [Authentication](#authentication)
|
||||
- [Add extra identities](#add-extra-identities)
|
||||
* [Signing](#signing)
|
||||
* [Encryption](#encryption)
|
||||
* [Authentication](#authentication)
|
||||
* [Add extra identities](#add-extra-identities)
|
||||
- [Verify](#verify)
|
||||
- [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)
|
||||
- [Enable KDF](#enable-kdf)
|
||||
- [Set information](#set-information)
|
||||
* [Change PIN](#change-pin)
|
||||
* [Enable KDF](#enable-kdf)
|
||||
* [Set information](#set-information)
|
||||
- [Transfer keys](#transfer-keys)
|
||||
- [Signing](#signing-1)
|
||||
- [Encryption](#encryption-1)
|
||||
- [Authentication](#authentication-1)
|
||||
* [Signing](#signing-1)
|
||||
* [Encryption](#encryption-1)
|
||||
* [Authentication](#authentication-1)
|
||||
- [Verify card](#verify-card)
|
||||
- [Multiple YubiKeys](#multiple-yubikeys)
|
||||
- [Cleanup](#cleanup)
|
||||
- [Using keys](#using-keys)
|
||||
- [Rotating keys](#rotating-keys)
|
||||
- [Setup environment](#setup-environment)
|
||||
- [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)
|
||||
- [Adding notations](#adding-notations)
|
||||
- [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)
|
||||
- [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)
|
||||
- [Chained SSH Agent Forwarding](#chained-ssh-agent-forwarding)
|
||||
- [GitHub](#github)
|
||||
- [OpenBSD](#openbsd-1)
|
||||
- [Windows](#windows-1)
|
||||
- [WSL](#wsl)
|
||||
* [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)
|
||||
* [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)
|
||||
- [Chained SSH Agent Forwarding](#chained-ssh-agent-forwarding)
|
||||
* [GitHub](#github)
|
||||
* [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)
|
||||
- [macOS](#macos-1)
|
||||
* [macOS](#macos-1)
|
||||
- [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)
|
||||
* [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)
|
||||
- [Mailvelope on macOS](#mailvelope-on-macos)
|
||||
- [Mutt](#mutt)
|
||||
* [Mailvelope on macOS](#mailvelope-on-macos)
|
||||
* [Mutt](#mutt)
|
||||
- [Reset](#reset)
|
||||
- [Recovery after reset](#recovery-after-reset)
|
||||
- [Notes](#notes)
|
||||
@ -86,11 +86,12 @@ If you have a comment or suggestion, please open an [Issue](https://github.com/d
|
||||
- [Alternatives](#alternatives)
|
||||
- [Links](#links)
|
||||
|
||||
|
||||
# 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.
|
||||
|
||||
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).
|
||||
|
||||
@ -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.
|
||||
|
||||
|
||||
## OpenBSD
|
||||
|
||||
```console
|
||||
@ -343,11 +345,9 @@ From YubiKey firmware version 5.2.3 onwards - which introduces "Enhancements to
|
||||
## 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
|
||||
@ -447,7 +447,7 @@ Disable networking for the remainder of the setup.
|
||||
|
||||
# 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.
|
||||
|
||||
@ -471,37 +471,97 @@ 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`.
|
||||
|
||||
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
|
||||
|
||||
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:
|
||||
Do not set the master key to expire - see [Note #3](#notes).
|
||||
|
||||
```console
|
||||
$ gpg --batch --generate-key gen-params-rsa4096
|
||||
gpg: Generating a basic OpenPGP key
|
||||
gpg: key 0xEA5DE91459B80592 marked as ultimately trusted
|
||||
gpg: revocation certificate stored as '/tmp.FLZC0xcM/openpgp-revocs.d/D6F924841F78D62C65ABB9588B461860159FFB7B.rev'
|
||||
gpg: done
|
||||
$ gpg --expert --full-generate-key
|
||||
|
||||
Please select what kind of key you want:
|
||||
(1) RSA and RSA (default)
|
||||
(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
|
||||
$ gpg --list-key
|
||||
gpg: checking the trustdb
|
||||
gpg: marginals needed: 3 completes needed: 1 trust model: pgp
|
||||
gpg: depth: 0 valid: 1 signed: 0 trust: 0-, 0q, 0n, 0m, 0f, 1u
|
||||
/tmp.FLZC0xcM/pubring.kbx
|
||||
-------------------------------
|
||||
pub rsa4096/0xFF3E7D88647EBCDB 2021-08-22 [C]
|
||||
Key fingerprint = 011C E16B D45B 27A5 5BA8 776D FF3E 7D88 647E BCDB
|
||||
uid [ultimate] Dr Duh <doc@duh.to>
|
||||
```
|
||||
GnuPG needs to construct a user ID to identify your key.
|
||||
|
||||
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.
|
||||
Real name: Dr Duh
|
||||
Email address: doc@duh.to
|
||||
Comment: [Optional - leave blank]
|
||||
You selected this USER-ID:
|
||||
"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
|
||||
uid Dr Duh <doc@duh.to>
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
@ -527,61 +587,214 @@ $ gpg --default-key $OLDKEY --sign-key $KEYID
|
||||
|
||||
# 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).
|
||||
|
||||
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):
|
||||
Edit the master key to add sub-keys:
|
||||
|
||||
```console
|
||||
$ gpg --quick-add-key "011C E16B D45B 27A5 5BA8 776D FF3E 7D88 647E BCDB" \
|
||||
rsa4096 sign 1y
|
||||
$ gpg --expert --edit-key $KEYID
|
||||
|
||||
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
|
||||
$ gpg --quick-add-key "011C E16B D45B 27A5 5BA8 776D FF3E 7D88 647E BCDB" \
|
||||
rsa4096 encrypt 1y
|
||||
gpg> addkey
|
||||
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
|
||||
$ gpg --quick-add-key "011C E16B D45B 27A5 5BA8 776D FF3E 7D88 647E BCDB" \
|
||||
rsa4096 auth 1y
|
||||
gpg> addkey
|
||||
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
|
||||
$ gpg --list-keys
|
||||
/tmp.FLZC0xcM/pubring.kbx
|
||||
-------------------------------
|
||||
pub rsa4096/0xFF3E7D88647EBCDB 2021-08-22 [C]
|
||||
Key fingerprint = 011C E16B D45B 27A5 5BA8 776D FF3E 7D88 647E BCDB
|
||||
uid [ultimate] Dr Duh <doc@duh.to>
|
||||
sub rsa4096/0xBECFA3C1AE191D15 2017-10-09 [S] [expires: 2018-10-09]
|
||||
sub rsa4096/0x5912A795E90DD2CF 2017-10-09 [E] [expires: 2018-10-09]
|
||||
sub rsa4096/0x3F29127E79649A3D 2017-10-09 [A] [expires: 2018-10-09]
|
||||
gpg> addkey
|
||||
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? 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:
|
||||
|
||||
````console
|
||||
-gpg> save
|
||||
Finish by saving the keys.
|
||||
|
||||
```console
|
||||
gpg> save
|
||||
```
|
||||
|
||||
## Add extra identities
|
||||
|
||||
(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:
|
||||
(Optional) To add additional email addresses or identities, use `adduid`:
|
||||
|
||||
```console
|
||||
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.
|
||||
|
||||
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:
|
||||
|
||||
```console
|
||||
``` console
|
||||
$ 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
|
||||
|
||||
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.
|
||||
|
||||
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**
|
||||
|
||||
@ -873,6 +1087,7 @@ $ sudo umount /mnt/encrypted-storage/
|
||||
$ sudo cryptsetup luksClose secret
|
||||
```
|
||||
|
||||
|
||||
**OpenBSD**
|
||||
|
||||
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
|
||||
|
||||
**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.
|
||||
|
||||
@ -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.
|
||||
|
||||
## 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.
|
||||
|
||||
```console
|
||||
@ -1091,19 +1305,19 @@ gpg/card> kdf-setup
|
||||
|
||||
## 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 |
|
||||
| ---------- | ------------- | ------------------------------------------------------------------------------------------ |
|
||||
| PIN | `123456` | decrypt and authenticate (SSH) |
|
||||
| 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)) |
|
||||
Name | Default Value | Use
|
||||
-----------|---------------|-------------------------------------------------------------
|
||||
PIN | `123456` | decrypt and authenticate (SSH)
|
||||
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))
|
||||
|
||||
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:
|
||||
|
||||
@ -1330,35 +1544,40 @@ $ cd $GNUPGHOME
|
||||
```
|
||||
|
||||
## 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).
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
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:
|
||||
|
||||
Insert the first Yubikey (which has a different serial number) and run the following command:
|
||||
|
||||
|
||||
```console
|
||||
$ 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.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
# Cleanup
|
||||
|
||||
Ensure you have:
|
||||
|
||||
- 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 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 the password to that encrypted volume in a separate location.
|
||||
- Saved a copy of the public key somewhere easily accessible later.
|
||||
* 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 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 the password to that encrypted volume in a separate location.
|
||||
* 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:
|
||||
|
||||
@ -1617,7 +1836,7 @@ Secret key is available
|
||||
|
||||
## 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.
|
||||
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:
|
||||
|
||||
@ -1683,7 +1902,7 @@ ssb* rsa4096/0x3F29127E79649A3D
|
||||
[ultimate] (1). Dr Duh <doc@duh.to>
|
||||
```
|
||||
|
||||
Then, use the `expire` command to set a new expiration date. (Despite the name, this will not cause currently valid keys to become expired.)
|
||||
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
|
||||
@ -1696,7 +1915,6 @@ Please specify how long the key should be valid.
|
||||
<n>y = key expires in n years
|
||||
Key is valid for? (0)
|
||||
```
|
||||
|
||||
Follow these prompts to set a new expiration date, then `save` to save your changes.
|
||||
|
||||
Next, export the public key:
|
||||
@ -1711,11 +1929,11 @@ Transfer that public key to the computer from which you use your GPG key, and th
|
||||
$ gpg --import gpg-0x*.asc
|
||||
```
|
||||
|
||||
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.
|
||||
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.
|
||||
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:
|
||||
|
||||
@ -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.
|
||||
|
||||
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:
|
||||
|
||||
@ -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):
|
||||
|
||||
```fish
|
||||
set -x GPG_TTY (tty)
|
||||
set -x 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 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
|
||||
|
||||
@ -1951,11 +2168,11 @@ The latter one may be more insecure as raw socket is just forwarded (not like `S
|
||||
|
||||
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
|
||||
### Use ssh-agent
|
||||
|
||||
In the above steps, you have successfully configured a local ssh-agent.
|
||||
|
||||
You should now be able to 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.)
|
||||
You should now be able to 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
|
||||
|
||||
@ -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.
|
||||
|
||||
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
|
||||
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
|
||||
|
||||
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
|
||||
Host third
|
||||
@ -2005,7 +2222,7 @@ Host third
|
||||
# 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
|
||||
|
||||
@ -2015,7 +2232,7 @@ Login to GitHub and upload SSH and PGP public keys in Settings.
|
||||
|
||||
To configure a signing key:
|
||||
|
||||
> git config --global user.signingkey $KEYID
|
||||
> git config --global user.signingkey $KEYID
|
||||
|
||||
Make sure the user.email option matches the email address associated with the PGP identity.
|
||||
|
||||
@ -2027,8 +2244,8 @@ To authenticate:
|
||||
|
||||
Run the following commands:
|
||||
|
||||
> git config --global core.sshcommand 'plink -agent'
|
||||
> git config --global gpg.program 'C:\Program Files (x86)\GnuPG\bin\gpg.exe'
|
||||
> git config --global core.sshcommand 'plink -agent'
|
||||
> git config --global gpg.program 'C:\Program Files (x86)\GnuPG\bin\gpg.exe'
|
||||
|
||||
You can then change the repository url to `git@github.com:USERNAME/repository` and any authenticated commands will be authorized by YubiKey.
|
||||
|
||||
@ -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:
|
||||
|
||||
```powershell
|
||||
``` 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:
|
||||
* 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>
|
||||
```
|
||||
|
||||
- Create or edit `%APPDATA%/gnupg/gpg-agent.conf` to add:
|
||||
* Create or edit `%APPDATA%/gnupg/gpg-agent.conf` to add:
|
||||
|
||||
```
|
||||
enable-ssh-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 /bye
|
||||
```
|
||||
|
||||
- Enter `> gpg --card-status` to see YubiKey details.
|
||||
- Import the [public key](#export-public-key): `> gpg --import <path to public key file>`
|
||||
- [Trust the master key](#trust-master-key)
|
||||
- Retrieve the public key id: `> gpg --list-public-keys`
|
||||
- Export the SSH key from GPG: `> gpg --export-ssh-key <public key id>`
|
||||
* Enter `> gpg --card-status` to see YubiKey details.
|
||||
* Import the [public key](#export-public-key): `> gpg --import <path to public key file>`
|
||||
* [Trust the master key](#trust-master-key)
|
||||
* Retrieve the public key id: `> gpg --list-public-keys`
|
||||
* 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.
|
||||
|
||||
@ -2104,9 +2321,9 @@ Another way is to forward the gpg ssh socket, as described below.
|
||||
|
||||
#### Prerequisites
|
||||
|
||||
- Ubuntu 16.04 or newer for WSL
|
||||
- Kleopatra
|
||||
- [Windows configuration](#windows)
|
||||
* Ubuntu 16.04 or newer for WSL
|
||||
* Kleopatra
|
||||
* [Windows configuration](#windows)
|
||||
|
||||
#### WSL configuration
|
||||
|
||||
@ -2126,7 +2343,7 @@ RemoteForward <remote SSH socket path> /tmp/S.weasel-pageant
|
||||
|
||||
#### Remote host configuration
|
||||
|
||||
You may have to add the following to the shell rc file.
|
||||
You may have to add the following to the shell rc file.
|
||||
|
||||
```
|
||||
export SSH_AUTH_SOCK=$(gpgconf --list-dirs agent-ssh-socket)
|
||||
@ -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.
|
||||
|
||||
**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`
|
||||
|
||||
@ -2262,22 +2479,22 @@ Host
|
||||
# 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
|
||||
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.
|
||||
|
||||
## 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
|
||||
Host third
|
||||
@ -2287,9 +2504,9 @@ Host third
|
||||
# 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
|
||||
|
||||
@ -2403,11 +2620,13 @@ To allow Chrome to run gpgme, edit `~/Library/Application\ Support/Google/Chrome
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "gpgmejson",
|
||||
"description": "Integration with GnuPG",
|
||||
"path": "/usr/local/bin/gpgme-json",
|
||||
"type": "stdio",
|
||||
"allowed_origins": ["chrome-extension://kajibbejlbohfaggdiogboambcijhkke/"]
|
||||
"name": "gpgmejson",
|
||||
"description": "Integration with GnuPG",
|
||||
"path": "/usr/local/bin/gpgme-json",
|
||||
"type": "stdio",
|
||||
"allowed_origins": [
|
||||
"chrome-extension://kajibbejlbohfaggdiogboambcijhkke/"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
@ -2469,7 +2688,7 @@ Before you unmount your backup, ask yourself if you should make another one just
|
||||
|
||||
# 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. 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.
|
||||
@ -2512,20 +2731,17 @@ 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, `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
|
||||
`~/.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
|
||||
following error on `pass insert`:
|
||||
|
||||
```
|
||||
gpg: 0x0000000000000000: There is no assurance this key belongs to the named user
|
||||
gpg: [stdin]: encryption failed: Unusable public key
|
||||
```
|
||||
|
||||
you need to adjust the trust associated with the key. See the above bullet.
|
||||
```
|
||||
gpg: 0x0000000000000000: There is no assurance this key belongs to the named user
|
||||
gpg: [stdin]: encryption failed: Unusable public key
|
||||
```
|
||||
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.
|
||||
|
||||
@ -2533,29 +2749,29 @@ Before you unmount your backup, ask yourself if you should make another one just
|
||||
|
||||
# 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
|
||||
|
||||
- https://alexcabal.com/creating-the-perfect-gpg-keypair/
|
||||
- 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.onefellow.com/post/180065697833/yubikey-forwarding-ssh-keys
|
||||
- https://developers.yubico.com/PGP/
|
||||
- https://developers.yubico.com/PGP/Card_edit.html
|
||||
- https://developers.yubico.com/yubikey-personalization/
|
||||
- https://evilmartians.com/chronicles/stick-with-security-yubikey-ssh-gnupg-macos
|
||||
- https://gist.github.com/ageis/14adc308087859e199912b4c79c4aaa4
|
||||
- https://github.com/herlo/ssh-gpg-smartcard-config
|
||||
- https://github.com/tomlowenthal/documentation/blob/master/gpg/smartcard-keygen.md
|
||||
- https://help.riseup.net/en/security/message-security/openpgp/best-practices
|
||||
- https://jclement.ca/articles/2015/gpg-smartcard/
|
||||
- https://rnorth.org/gpg-and-ssh-with-yubikey-for-mac
|
||||
- https://trmm.net/Yubikey
|
||||
- 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.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
|
||||
- https://support.yubico.com/support/solutions/articles/15000027139-yubikey-5-2-3-enhancements-to-openpgp-3-4-support
|
||||
* https://alexcabal.com/creating-the-perfect-gpg-keypair/
|
||||
* 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.onefellow.com/post/180065697833/yubikey-forwarding-ssh-keys
|
||||
* https://developers.yubico.com/PGP/
|
||||
* https://developers.yubico.com/PGP/Card_edit.html
|
||||
* https://developers.yubico.com/yubikey-personalization/
|
||||
* https://evilmartians.com/chronicles/stick-with-security-yubikey-ssh-gnupg-macos
|
||||
* https://gist.github.com/ageis/14adc308087859e199912b4c79c4aaa4
|
||||
* https://github.com/herlo/ssh-gpg-smartcard-config
|
||||
* https://github.com/tomlowenthal/documentation/blob/master/gpg/smartcard-keygen.md
|
||||
* https://help.riseup.net/en/security/message-security/openpgp/best-practices
|
||||
* https://jclement.ca/articles/2015/gpg-smartcard/
|
||||
* https://rnorth.org/gpg-and-ssh-with-yubikey-for-mac
|
||||
* https://trmm.net/Yubikey
|
||||
* 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.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
|
||||
* https://support.yubico.com/support/solutions/articles/15000027139-yubikey-5-2-3-enhancements-to-openpgp-3-4-support
|
||||
|
||||
Loading…
Reference in New Issue
Block a user