diff options
Diffstat (limited to '')
| -rw-r--r-- | README.md | 57 |
1 files changed, 47 insertions, 10 deletions
@@ -4,6 +4,8 @@ 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 PUK (Pin Unblock Key) may be set to its default value of `12345678`. An attacker can use this to reset your PIN and use your Yubikey. Please see the [Change PUK](#change-puk) section for details on how to change your PUK. + If you have a comment or suggestion, please open an [Issue](https://github.com/drduh/YubiKey-Guide/issues) on GitHub. - [Purchase](#purchase) @@ -34,6 +36,7 @@ If you have a comment or suggestion, please open an [Issue](https://github.com/d - [Export public keys](#export-public-keys) - [Configure Smartcard](#configure-smartcard) * [Change PIN](#change-pin) + * [Change PUK](#change-puk) * [Set information](#set-information) - [Transfer keys](#transfer-keys) * [Signing](#signing-1) @@ -261,7 +264,7 @@ Generate a NixOS LiveCD image with the given config: let config = { pkgs, ... }: with pkgs; { - imports = [ <nixpkgs/nixos/modules/installer/cd-dvd/installation-cd-graphical-kde.nix> ]; + imports = [ <nixpkgs/nixos/modules/installer/cd-dvd/installation-cd-graphical-plasma5.nix> ]; boot.kernelPackages = linuxPackages_latest; @@ -340,7 +343,7 @@ 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 +```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. @@ -1283,9 +1286,17 @@ Use the [YubiKey Manager](https://developers.yubico.com/yubikey-manager) applica ## Change PIN -The default PIN is `123456` and default Admin PIN (PUK) is `12345678`. CCID-mode PINs can be up to 127 ASCII characters. They have to be at least 6 (PIN) or 8 (PUK) ASCII characters. +Your Yubikey has 2 PINs: The user PIN, which is used for end-user functionality such as signing and encryption and an admin PIN which is required for updating your information on the Yubikey. Entering the user PIN incorrectly three times consecutively will cause the PIN to become blocked. + +Name|Default Value +---|--- +PIN|`123456` +Admin PIN|`12345678` +PUK|`12345678` -The Admin PIN is required for some card operations and to unblock a PIN that has been entered incorrectly more than three times. See the GnuPG documentation on [Managing PINs](https://www.gnupg.org/howtos/card-howto/en/ch03s02.html) for details. +CCID-mode PINs can be up to 127 ASCII characters. They have to be at least 6 (PIN) or 8 (PUK) ASCII characters. See the GnuPG documentation on [Managing PINs](https://www.gnupg.org/howtos/card-howto/en/ch03s02.html) for details. + +First set your admin and user PINs: ```console gpg/card> admin @@ -1321,6 +1332,19 @@ Q - quit Your selection? q ``` +## Change PUK + +The PUK (Pin Unlock Key) can be used to reset the PIN if it is ever lost or becomes blocked after the maximum number of incorrect attempts (default 3). The default PUK is `12345678`. If the PUK is also entered incorrectly three times, the key is permanently irrecoverable. You can set your PUK to the same as your daily PIN, giving you a total of 6 attempts. + +```console +ykman piv change-puk + +Enter your current PUK: +Enter your new PUK: +Repeat for confirmation: +New PUK set. +``` + ## Set information Some fields are optional. @@ -1942,6 +1966,8 @@ It is now possible to continue following the Keyoxide guide and upload the key t # 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)._ + [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. When importing the key to `gpg-agent`, you'll be prompted for a passphrase to protect that key within GPG's key store - you may want to use the same passphrase as the original's ssh version. GPG can both cache passphrases for a determined period (ref. `gpg-agent`'s various `cache-ttl` options), and since version 2.1 can store and fetch passphrases via the macOS keychain. Note than when removing the old private key after importing to `gpg-agent`, keep the `.pub` key file around for use in specifying ssh identities (e.g. `ssh -i /path/to/identity.pub`). @@ -2485,33 +2511,33 @@ To require a touch for each key operation, install [YubiKey Manager](https://dev Authentication: ```console -$ ykman openpgp set-touch aut on +$ ykman openpgp keys set-touch aut on ``` Signing: ```console -$ ykman openpgp set-touch sig on +$ ykman openpgp keys set-touch sig on ``` Encryption: ```console -$ ykman openpgp set-touch enc on +$ ykman openpgp keys set-touch enc on ``` Depending on how the YubiKey is going to be used, you may want to look at the policy options for each of these and adjust the above commands accordingly. They can be viewed with the following command: ``` -$ ykman openpgp set-touch -h -Usage: ykman openpgp set-touch [OPTIONS] KEY POLICY +$ ykman openpgp keys set-touch -h +Usage: ykman openpgp keys set-touch [OPTIONS] KEY POLICY Set touch policy for OpenPGP keys. KEY Key slot to set (sig, enc, aut or att). POLICY Touch policy to set (on, off, fixed, cached or cached-fixed). - The touch policy is used to require user interaction for all operations using the private key on the YubiKey. The touch policy is set indivdually for each key slot. To see the current touch policy, run + The touch policy is used to require user interaction for all operations using the private key on the YubiKey. The touch policy is set individually for each key slot. To see the current touch policy, run $ ykman openpgp info @@ -2659,6 +2685,17 @@ Admin PIN: 12345678 - 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 + `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. - If you receive the error, `gpg: 0x0000000000000000: skipped: Unusable public key` or `encryption failed: Unusable public key` the sub-key may be expired and can no longer be used to encrypt nor sign messages. It can still be used to decrypt and authenticate, however. |