knowledge
/
YubiKey-Guide
mirror of https://github.com/drduh/YubiKey-Guide.git
1
0
Fork 0
Code Issues Releases Activity

Update toc

This commit is contained in:
drduh 2022-12-26 14:44:27 -08:00
parent 33d0f87a34
commit e823203503
1 changed files with 57 additions and 55 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

112
README.md
View File

@ -11,84 +11,86 @@ If you have a comment or suggestion, please open an [Issue](https://github.com/d
- [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)
* [Fedora](#fedora) - [Fedora](#fedora)
* [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)
- [YubiKey](#yubikey)
- [OneRNG](#onerng)
- [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) - [Enable KDF](#enable-kdf)
* [Enable KDF](#enable-kdf) - [Change PIN](#change-pin)
* [Set information](#set-information) - [Set information](#set-information)
- [Transfer keys](#transfer-keys) - [Transfer keys](#transfer-keys)
* [Signing](#signing-1) - [Signing](#signing)
* [Encryption](#encryption-1) - [Encryption](#encryption)
* [Authentication](#authentication-1) - [Authentication](#authentication)
- [Verify card](#verify-card) - [Verify card](#verify-card)
- [Multiple YubiKeys](#multiple-yubikeys) - [Multiple YubiKeys](#multiple-yubikeys)
- [Switching between two or more Yubikeys](#switching-between-two-or-more-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)
- [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)
* [Windows](#windows-1) - [Windows](#windows)
+ [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)
- [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)
- [Troubleshooting](#troubleshooting) - [Troubleshooting](#troubleshooting)
- [Alternatives](#alternatives) - [Alternatives](#alternatives)
* [Create keys with batch](#create-keys-with-batch) - [Create keys with batch](#create-keys-with-batch)
- [Links](#links) - [Links](#links)
# Purchase # Purchase
All YubiKeys except the blue "security key" model and the "Bio Series - FIDO Edition" 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/). A list of the YubiKeys compatible with OpenPGP is available [here](https://support.yubico.com/hc/en-us/articles/360013790259-Using-Your-YubiKey-with-OpenPGP). In May 2021, Yubico also 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 and the "Bio Series - FIDO Edition" 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/). A list of the YubiKeys compatible with OpenPGP is available [here](https://support.yubico.com/hc/en-us/articles/360013790259-Using-Your-YubiKey-with-OpenPGP). In May 2021, Yubico also 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.
@ -2113,7 +2115,7 @@ It is now possible to continue following the Keyoxide guide and upload the key t
# SSH # SSH
_Note that if you want to use a **YubiKey ONLY for SSH** (and don't really care about PGP/GPG), then [since OpenSSH v8.2](https://www.openssh.com/txt/release-8.2) you alternatively can simply `ssh-keygen -t ed25519-sk` (without requiring anything else from this guide!), as explained [e.g. in this guide](https://github.com/vorburger/vorburger.ch-Notes/blob/develop/security/ed25519-sk.md). Yubico also recently announced support for resident ssh keys under OpenSSH 8.2+ on their blue "security key 5 nfc" as mentioned in their [blog post](https://www.yubico.com/blog/github-now-supports-ssh-security-keys/)._ **Tip** If you want to use a YubiKey for SSH only (and don't really care about PGP/GPG), then [since OpenSSH v8.2](https://www.openssh.com/txt/release-8.2) you alternatively can simply `ssh-keygen -t ed25519-sk` (without requiring anything else from this guide!), as explained [in this guide](https://github.com/vorburger/vorburger.ch-Notes/blob/develop/security/ed25519-sk.md). Yubico also recently announced support for resident ssh keys under OpenSSH 8.2+ on their blue "security key 5 nfc" as mentioned in their [blog post](https://www.yubico.com/blog/github-now-supports-ssh-security-keys/)._
[gpg-agent](https://wiki.archlinux.org/index.php/GnuPG#SSH_agent) supports the OpenSSH ssh-agent protocol (`enable-ssh-support`), as well as Putty's Pageant on Windows (`enable-putty-support`). This means it can be used instead of the traditional ssh-agent / pageant. There are some differences from ssh-agent, notably that gpg-agent does not _cache_ keys rather it converts, encrypts and stores them - persistently - as GPG keys and then makes them available to ssh clients. Any existing ssh private keys that you'd like to keep in `gpg-agent` should be deleted after they've been imported to the GPG agent. [gpg-agent](https://wiki.archlinux.org/index.php/GnuPG#SSH_agent) supports the OpenSSH ssh-agent protocol (`enable-ssh-support`), as well as Putty's Pageant on Windows (`enable-putty-support`). This means it can be used instead of the traditional ssh-agent / pageant. There are some differences from ssh-agent, notably that gpg-agent does not _cache_ keys rather it converts, encrypts and stores them - persistently - as GPG keys and then makes them available to ssh clients. Any existing ssh private keys that you'd like to keep in `gpg-agent` should be deleted after they've been imported to the GPG agent.
@ -2714,7 +2716,7 @@ YubiKey will blink when it is waiting for a touch. On Linux you can also use [yu
GPG keys on YubiKey can be used with ease to encrypt and/or sign emails and attachments using [Thunderbird](https://www.thunderbird.net/), [Enigmail](https://www.enigmail.net) and [Mutt](http://www.mutt.org/). Thunderbird supports OAuth 2 authentication and can be used with Gmail. See [this guide](https://ssd.eff.org/en/module/how-use-pgp-linux) from EFF for detailed instructions. Mutt has OAuth 2 support since version 2.0. GPG keys on YubiKey can be used with ease to encrypt and/or sign emails and attachments using [Thunderbird](https://www.thunderbird.net/), [Enigmail](https://www.enigmail.net) and [Mutt](http://www.mutt.org/). Thunderbird supports OAuth 2 authentication and can be used with Gmail. See [this guide](https://ssd.eff.org/en/module/how-use-pgp-linux) from EFF for detailed instructions. Mutt has OAuth 2 support since version 2.0.
## Mailvelope on macOS ## Mailvelope
[Mailvelope](https://www.mailvelope.com/en) allows GPG keys on YubiKey to be used with Gmail and others. [Mailvelope](https://www.mailvelope.com/en) allows GPG keys on YubiKey to be used with Gmail and others.
@ -2790,7 +2792,7 @@ Reset code: NOT SET
Admin PIN: 12345678 Admin PIN: 12345678
``` ```
# Recovery after reset ## Recovery after reset
If for whatever reason you need to reinstate your YubiKey from your master key backup (such as the one stored on an encrypted USB described in [Backup](#backup)), follow the following steps in [Rotating keys](#rotating-keys) to setup your environment, and then follow the steps of again [Configure Smartcard](#configure-smartcard). If for whatever reason you need to reinstate your YubiKey from your master key backup (such as the one stored on an encrypted USB described in [Backup](#backup)), follow the following steps in [Rotating keys](#rotating-keys) to setup your environment, and then follow the steps of again [Configure Smartcard](#configure-smartcard).
@ -2846,13 +2848,12 @@ Before you unmount your backup, ask yourself if you should make another one just
- If, when you try the above `--edit-key` command, you get the error `Need the secret key to do this` - manually specify trust for the key in `~/.gnupg/gpg.conf` by using the `trust-key [key ID]` directive. - If, when you try the above `--edit-key` command, you get the error `Need the secret key to do this` - manually specify trust for the key in `~/.gnupg/gpg.conf` by using the `trust-key [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`, you need to adjust the trust associated with the key. See the note above.
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.
- 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.
@ -2867,7 +2868,7 @@ Before you unmount your backup, ask yourself if you should make another one just
## Create keys with batch ## Create keys with batch
Keys can also be generated using template files and the `--batch` parameter - see [GnuPG documentation](https://www.gnupg.org/documentation/manuals/gnupg/Unattended-GPG-key-generation.html) Keys can also be generated using template files and the `batch` parameter - see [GnuPG documentation](https://www.gnupg.org/documentation/manuals/gnupg/Unattended-GPG-key-generation.html).
Start from the [gen-params-rsa4096](contrib/gen-params-rsa4096) template. If you're using GnuPG v2.1.7 or newer, you can also use the ([gen-params-ed25519](contrib/gen-params-ed25519) template. These templates will not set the master key to expire - see [Note #3](#notes). Start from the [gen-params-rsa4096](contrib/gen-params-rsa4096) template. If you're using GnuPG v2.1.7 or newer, you can also use the ([gen-params-ed25519](contrib/gen-params-ed25519) template. These templates will not set the master key to expire - see [Note #3](#notes).
@ -2922,6 +2923,7 @@ $ gpg --quick-add-key "011C E16B D45B 27A5 5BA8 776D FF3E 7D88 647E BCDB" \
rsa4096 auth 1y rsa4096 auth 1y
``` ```
Continue with the Verify section of this guide.
# Links # Links