From b745f1d90e4e3c778f6918ae7794a6aa595c2744 Mon Sep 17 00:00:00 2001 From: drduh Date: Sun, 2 Jun 2019 10:32:16 -0700 Subject: [PATCH] Add card reset steps, clean up formatting. --- README.md | 143 ++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 90 insertions(+), 53 deletions(-) diff --git a/README.md b/README.md index 7c0ebf4..e4a8b8c 100644 --- a/README.md +++ b/README.md @@ -37,7 +37,6 @@ If you have a comment or suggestion, please open an [Issue](https://github.com/d * [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) - * [Touch to authenticate](#touch-to-authenticate) * [Import SSH keys](#import-ssh-keys) * [Remote Machines (agent forwarding)](#remote-machines--agent-forwarding-) * [GitHub](#github) @@ -47,9 +46,10 @@ If you have a comment or suggestion, please open an [Issue](https://github.com/d - [Prerequisites](#prerequisites) - [WSL configuration](#wsl-configuration) - [Remote host configuration](#remote-host-configuration) - - [Final test](#final-test) -- [Using multiple YubiKey with same GPG keys](#Using-multiple-YubiKey-with-same-GPG-keys) +- [Multiple keys](#Multiple-keys) +- [Require touch](#require-touch) - [Email](#email) +- [Reset](#reset) - [Notes](#notes) - [Troubleshooting](#troubleshooting) - [Links](#links) @@ -613,7 +613,11 @@ ssb rsa4096/0x5912A795E90DD2CF ssb rsa4096/0x3F29127E79649A3D created: 2017-10-09 expires: 2018-10-09 usage: A [ultimate] (1). Dr Duh +``` +Finish by saving the keys. + +```console gpg> save ``` @@ -635,7 +639,7 @@ ssb rsa4096/0x3F29127E79649A3D 2017-10-09 [A] [expires: 2018-10-09] Add any additional identities or email addresses you wish to associate using the `adduid` command. -**Optional** Verify with OpenPGP key checks, use the automated [key best practice checker](https://riseup.net/en/security/message-security/openpgp/best-practices#openpgp-key-checks): +**Tip** Verify with a OpenPGP [key best practice checker](https://riseup.net/en/security/message-security/openpgp/best-practices#openpgp-key-checks): ```console $ gpg --export $KEYID | hokey lint @@ -669,6 +673,8 @@ $ gpg --armor --export-secret-subkeys $KEYID -o \path\to\dir\sub.gpg Once GPG keys are moved to YubiKey, they cannot be moved again! Create an **encrypted** backup of the keyring and consider using a [paper copy](https://www.jabberwocky.com/software/paperkey/) of the keys as an additional backup. +**Tip**: The ext2 filesystem (without encryption) can be mounted on both Linux and OpenBSD. + **Linux** Attach another external storage device and check its label: @@ -1266,7 +1272,7 @@ gpg: Total number processed: 1 gpg: imported: 1 ``` -Edit the master key to assign it ultimate trust by selecting `trust` then option `5`: +Edit the master key to assign it ultimate trust by selecting `trust` and `5`: ```console $ export KEYID=0xFF3E7D88647EBCDB @@ -1470,16 +1476,18 @@ Probably the biggest thing missing from `gpg-agent`'s ssh agent support is being Create a hardened configuration for gpg-agent by downloading [drduh/config/gpg-agent.conf](https://github.com/drduh/config/blob/master/gpg-agent.conf): ```console -$ curl -o ~/.gnupg/gpg-agent.conf https://raw.githubusercontent.com/drduh/config/master/gpg-agent.conf +$ cd ~/.gnupg -$ cat ~/.gnupg/gpg-agent.conf +$ wget https://raw.githubusercontent.com/drduh/config/master/gpg-agent.conf + +$ grep -ve "^#" gpg-agent.conf enable-ssh-support default-cache-ttl 60 max-cache-ttl 120 pinentry-program /usr/bin/pinentry-curses ``` -Alternatively, you may want to use `/usr/bin/pinentry-gnome3` for a GUI-based prompt. +**Tip** Set `pinentry-program /usr/bin/pinentry-gnome3` for a GUI-based prompt. On macOS, use `brew install pinentry-mac` and adjust the program path to suit. @@ -1563,26 +1571,6 @@ debug1: Authentication succeeded (publickey). **Note** To make multiple connections or securely transfer many files, consider using the [ControlMaster](https://en.wikibooks.org/wiki/OpenSSH/Cookbook/Multiplexing) ssh option. Also see [drduh/config/ssh_config](https://github.com/drduh/config/blob/master/ssh_config). -## Touch to authenticate - -**Note** This is not possible on YubiKey NEO. - -By default, YubiKey will perform key operations without requiring a touch from the user. To require a touch for every SSH authentication, use the [YubiKey Manager](https://developers.yubico.com/yubikey-manager/) and Admin PIN: - -```console -$ ykman openpgp touch aut on -``` - -To require a touch for signing and encryption operations: - -```console -$ ykman openpgp touch sig on - -$ ykman openpgp touch enc on -``` - -The YubiKey will blink when it's waiting for touch. - ## Import SSH keys If there are existing SSH keys that you wish to make available via `gpg-agent`, you'll need to import them. You should then remove the original private keys. When importing the key, `gpg-agent` uses the key's filename as the key's label; this makes it easier to follow where the key originated from. In this example, we're starting with just the YubiKey's key in place and importing `~/.ssh/id_rsa`: @@ -1785,25 +1773,24 @@ StreamLocalBindUnlink yes And reload the SSH daemon (e.g., `sudo service sshd reload`). -#### Final test +Unplug YubiKey, disconnect or reboot. Log back in to Windows, open a WSL console and enter `ssh-add -l` - you should see nothing. -- Unplug YubiKey, disconnect or reboot. -- Log back in to Windows, open a WSL console and enter `ssh-add -l` - you should see nothing. -- Plug in YubiKey, enter the same command to display the ssh key. -- Log in to the remote host, you should have the pinentry dialog asking for the YubiKey pin. -- On the remote host, type `ssh-add -l` - if you see the ssh key, that means forwarding works! +Plug in YubiKey, enter the same command to display the ssh key. + +Log in to the remote host, you should have the pinentry dialog asking for the YubiKey pin. + +On the remote host, type `ssh-add -l` - if you see the ssh key, that means forwarding works! **Note** Agent forwarding may be chained through multiple hosts - just follow the same [protocol](#remote-host-configuration) to configure each host. -# Using multiple YubiKey with same GPG keys +# multiple keys -If you want to store your keys on multiple YubiKey, you will see that GnuPG doesn't store the serial number of the first key it has seen. -This is a know issue [#T2291](https://dev.gnupg.org/T2291). For now if you lost one of your keys and want to use another one the only workaround -is to delete GnuPG's shadowed key (this is where the serial number is stored). +GnuPG doesn't store the serial number of the first key it has seen - [#T2291](https://dev.gnupg.org/T2291). -To do so, first of all you need to find the `Keygrip` number of each key : -``` -gpg2 --with-keygrip -k $KEYID +If a YubiKey is lost and replaced, delete GnuPG's shadowed key - where the serial number is stored. Find the `Keygrip` number of each key: + +```console +$ gpg --with-keygrip -k $KEYID pub rsa4096/0xFF3E7D88647EBCDB 2017-10-09 [C] Key fingerprint = 011C E16B D45B 27A5 5BA8 776D FF3E 7D88 647E BCDB Keygrip = 7A20855980A62C10569DE893157F38A696B1300E @@ -1816,25 +1803,77 @@ sub rsa4096/0x3F29127E79649A3D 2017-10-09 [A] [expires: 2018-10-09] Keygrip = 7EF25A1115294342F451BC1CDD0FA94395F2D074 ``` -Then delete all the shadow keys using their `Keygrip` number : -``` -cd .gnupg/private-keys-v1.d -rm 85D44BD52AD45C0852BD15BF41161EE9AE477398.key \ -A0AA3D9F626BDEA3B833F290C7BCA79216C8A996.key \ -7EF25A1115294342F451BC1CDD0FA94395F2D074.key +Then delete all the shadow keys using their `Keygrip` number: + +```console +$ cd .gnupg/private-keys-v1.d + +$ rm 85D44BD52AD45C0852BD15BF41161EE9AE477398.key \ + A0AA3D9F626BDEA3B833F290C7BCA79216C8A996.key \ + 7EF25A1115294342F451BC1CDD0FA94395F2D074.key ``` -Insert the new YubiKey simply run a card-status this will re-generate the shadow-keys : -``` -gpg2 --card-status +Insert the new YubiKey and re-generate shadow-keys by checking card status: + +```console +$ gpg --card-status ``` -Then try to use your key, it should work, without serial number error. +# Require touch + +**Note** This is not possible on YubiKey NEO. + +By default, YubiKey will perform encryption, signing and authentication operations without requiring any action from the user, after the key is plugged in and first unlocked with the PIN. + +To require a touch for each key operation, install [YubiKey Manager](https://developers.yubico.com/yubikey-manager/) and recall the Admin PIN: + +Authentication: + +```console +$ ykman openpgp touch aut on +``` + +Signing: + +```console +$ ykman openpgp touch sig on +``` + +Encryption: + +```console +$ ykman openpgp touch enc on +``` + +YubiKey will blink when it is waiting for a touch. + # Email GPG keys on YubiKey can be used with ease to encrypt or sign email messages and attachments using [Thunderbird](https://www.thunderbird.net/) and [Enigmail](https://www.enigmail.net). Thunderbird supports OAuth 2 authentication and can be used with Gmail. See [this guide](https://ssd.eff.org/en/module/how-use-pgp-linux) from EFF for detailed instructions. +# Reset + +If PIN attempts are exceeded, the card is locked and must be [reset](https://developers.yubico.com/ykneo-openpgp/ResetApplet.html) and set up again using the encrypted backup. + +Copy the following script to a file and run `gpg-connect-agent -R $file` to lock and terminate the card. Then re-insert YubiKey to reset. + +```console +/hex +scd serialno +scd apdu 00 20 00 81 08 40 40 40 40 40 40 40 40 +scd apdu 00 20 00 81 08 40 40 40 40 40 40 40 40 +scd apdu 00 20 00 81 08 40 40 40 40 40 40 40 40 +scd apdu 00 20 00 81 08 40 40 40 40 40 40 40 40 +scd apdu 00 20 00 83 08 40 40 40 40 40 40 40 40 +scd apdu 00 20 00 83 08 40 40 40 40 40 40 40 40 +scd apdu 00 20 00 83 08 40 40 40 40 40 40 40 40 +scd apdu 00 20 00 83 08 40 40 40 40 40 40 40 40 +scd apdu 00 e6 00 00 +scd apdu 00 44 00 00 +/echo Card has been successfully reset. +``` + # Notes 1. YubiKey has two configurations: one invoked with a short press, and the other with a long press. By default, the short-press mode is configured for HID OTP - a brief touch will emit an OTP string starting with `cccccccc`. If you rarely use the OTP mode, you can swap it to the second configuration via the YubiKey Personalization tool. If you *never* use OTP, you can disable it entirely using the [YubiKey Manager](https://developers.yubico.com/yubikey-manager) application (note, this not the similarly named YubiKey NEO Manager). @@ -1870,8 +1909,6 @@ GPG keys on YubiKey can be used with ease to encrypt or sign email messages and - If SSH authentication stil fails - add up to 3 `-v` flags to increase verbosity. -- If you totally screw up, you can [reset the card](https://developers.yubico.com/ykneo-openpgp/ResetApplet.html). - # Links * https://alexcabal.com/creating-the-perfect-gpg-keypair/