mirror of
https://github.com/drduh/YubiKey-Guide.git
synced 2024-12-23 06:08:06 +00:00
More entropy cleanup, move batch instructions to alt
This commit is contained in:
parent
ee84dc53ac
commit
33d0f87a34
155
README.md
155
README.md
@ -2,7 +2,7 @@ This is a guide to using [YubiKey](https://www.yubico.com/products/yubikey-hardw
|
|||||||
|
|
||||||
Keys stored on YubiKey are [non-exportable](http://web.archive.org/web/20201125172759/https://support.yubico.com/hc/en-us/articles/360016614880-Can-I-Duplicate-or-Back-Up-a-YubiKey-) (as opposed to file-based keys that are stored on disk) and are convenient for everyday use. Instead of having to remember and enter passphrases to unlock SSH/GPG keys, YubiKey needs only a physical touch after being unlocked with a PIN. All signing and encryption operations happen on the card, rather than in OS memory.
|
Keys stored on YubiKey are [non-exportable](http://web.archive.org/web/20201125172759/https://support.yubico.com/hc/en-us/articles/360016614880-Can-I-Duplicate-or-Back-Up-a-YubiKey-) (as opposed to file-based keys that are stored on disk) and are convenient for everyday use. Instead of having to remember and enter passphrases to unlock SSH/GPG keys, YubiKey needs only a physical touch after being unlocked with a PIN. All signing and encryption operations happen on the card, rather than in OS memory.
|
||||||
|
|
||||||
**New!** [drduh/Purse](https://github.com/drduh/Purse) is a password manager which uses GPG and YubiKey.
|
**Tip** [drduh/Purse](https://github.com/drduh/Purse) is a password manager which uses GPG and YubiKey to securely store and read credentials.
|
||||||
|
|
||||||
> **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.
|
||||||
|
|
||||||
@ -30,7 +30,6 @@ If you have a comment or suggestion, please open an [Issue](https://github.com/d
|
|||||||
* [Encryption](#encryption)
|
* [Encryption](#encryption)
|
||||||
* [Authentication](#authentication)
|
* [Authentication](#authentication)
|
||||||
* [Add extra identities](#add-extra-identities)
|
* [Add extra identities](#add-extra-identities)
|
||||||
- [Create keys with --batch and --quick-add-key](#create-keys-with---batch-and---quick-add-keys)
|
|
||||||
- [Verify](#verify)
|
- [Verify](#verify)
|
||||||
- [Export secret keys](#export-secret-keys)
|
- [Export secret keys](#export-secret-keys)
|
||||||
- [Revocation certificate](#revocation-certificate)
|
- [Revocation certificate](#revocation-certificate)
|
||||||
@ -86,6 +85,7 @@ If you have a comment or suggestion, please open an [Issue](https://github.com/d
|
|||||||
- [Notes](#notes)
|
- [Notes](#notes)
|
||||||
- [Troubleshooting](#troubleshooting)
|
- [Troubleshooting](#troubleshooting)
|
||||||
- [Alternatives](#alternatives)
|
- [Alternatives](#alternatives)
|
||||||
|
* [Create keys with batch](#create-keys-with-batch)
|
||||||
- [Links](#links)
|
- [Links](#links)
|
||||||
|
|
||||||
|
|
||||||
@ -470,33 +470,27 @@ You may also need more recent versions of [yubikey-personalization](https://deve
|
|||||||
|
|
||||||
Generating cryptographic keys requires high-quality [randomness](https://www.random.org/randomness/), measured as entropy.
|
Generating cryptographic keys requires high-quality [randomness](https://www.random.org/randomness/), measured as entropy.
|
||||||
|
|
||||||
Most operating systems use software-based pseudorandom number generators. On newer machines there are CPU based hardware random number generators (HRNG) or you can use a separate hardware device like the White Noise or [OneRNG](https://onerng.info/onerng/) will [increase the speed](https://lwn.net/Articles/648550/) of entropy generation and possibly the quality.
|
Most operating systems use software-based pseudorandom number generators or CPU-based hardware random number generators (HRNG).
|
||||||
|
|
||||||
YubiKey firmware version 5.2.3 introduced "Enhancements to OpenPGP 3.4 Support" - which can optionally gather additional entropy from YubiKey via the SmartCard interface.
|
Optionally, you can use a separate hardware device like [OneRNG](https://onerng.info/onerng/) to [increase the speed](https://lwn.net/Articles/648550/) of entropy generation and possibly also the quality.
|
||||||
|
|
||||||
## YubiKey
|
## YubiKey
|
||||||
|
|
||||||
To feed the system's PRNG with entropy generated by the YubiKey itself, issue:
|
YubiKey firmware version 5.2.3 introduced "Enhancements to OpenPGP 3.4 Support" - which can optionally gather additional entropy from YubiKey via the SmartCard interface.
|
||||||
|
|
||||||
|
To seed the kernel's PRNG with additional 512 bytes retrieved from the YubiKey:
|
||||||
|
|
||||||
```console
|
```console
|
||||||
$ echo "SCD RANDOM 512" | gpg-connect-agent | sudo tee /dev/random | hexdump -C
|
$ echo "SCD RANDOM 512" | gpg-connect-agent | sudo tee /dev/random | hexdump -C
|
||||||
```
|
```
|
||||||
|
|
||||||
This will seed the Linux kernel's PRNG with additional 512 bytes retrieved from the YubiKey.
|
|
||||||
|
|
||||||
## OneRNG
|
## OneRNG
|
||||||
|
|
||||||
Install [rng-tools](https://wiki.archlinux.org/index.php/Rng-tools) software:
|
Install [rng-tools](https://wiki.archlinux.org/index.php/Rng-tools) software:
|
||||||
|
|
||||||
```console
|
```console
|
||||||
$ sudo apt -y install at rng-tools python3-gnupg openssl
|
$ sudo apt -y install at rng-tools python3-gnupg openssl
|
||||||
```
|
|
||||||
|
|
||||||
If you have a hardware device other than the CPU based one, install the accompany software and point rng-tools to its `/dev/` device.
|
|
||||||
|
|
||||||
OneRNG specific example:
|
|
||||||
|
|
||||||
```
|
|
||||||
$ wget https://github.com/OneRNG/onerng.github.io/raw/master/sw/onerng_3.7-1_all.deb
|
$ wget https://github.com/OneRNG/onerng.github.io/raw/master/sw/onerng_3.7-1_all.deb
|
||||||
|
|
||||||
$ sha256sum onerng_3.7-1_all.deb
|
$ sha256sum onerng_3.7-1_all.deb
|
||||||
@ -577,7 +571,7 @@ $ gpg --gen-random --armor 0 24
|
|||||||
ydOmByxmDe63u7gqx2XI9eDgpvJwibNH
|
ydOmByxmDe63u7gqx2XI9eDgpvJwibNH
|
||||||
```
|
```
|
||||||
|
|
||||||
Use upper case letters for improved readability if they are written down:
|
Use upper case letters for improved readability if passwords are written down by hand:
|
||||||
|
|
||||||
```console
|
```console
|
||||||
$ LC_ALL=C tr -dc '[:upper:]' < /dev/urandom | fold -w 20 | head -n1
|
$ LC_ALL=C tr -dc '[:upper:]' < /dev/urandom | fold -w 20 | head -n1
|
||||||
@ -1010,77 +1004,6 @@ gpg> save
|
|||||||
|
|
||||||
By default, the last identity added will be the primary user ID - use `primary` to change that.
|
By default, the last identity added will be the primary user ID - use `primary` to change that.
|
||||||
|
|
||||||
# Create keys with `--batch` and `--quick-add-keys`
|
|
||||||
|
|
||||||
To remove some complexity from the process, we will show an alternate procedure to generate the keys using template files and the `--batch` parameter. For futher details, full GNUPG documentation can be found [at this link](https://www.gnupg.org/documentation/manuals/gnupg/Unattended-GPG-key-generation.html). This procedure will have just the same result as described above.
|
|
||||||
|
|
||||||
For your convenience you can start from this RSA4096 key template: [gen-params-rsa4096](contrib/gen-params-rsa4096). If you're using GnuPG v2.1.7 or newer we strongly recommend generating ED25519 keys ([gen-params-ed25519](contrib/gen-params-ed25519), the procedure is the same). These templates will not set the master key to expire - see [Note #3](#notes).
|
|
||||||
|
|
||||||
Generate a RSA4096 master key:
|
|
||||||
|
|
||||||
```console
|
|
||||||
$ 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
|
|
||||||
```
|
|
||||||
|
|
||||||
Let's check the result:
|
|
||||||
|
|
||||||
```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>
|
|
||||||
```
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
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):
|
|
||||||
|
|
||||||
```console
|
|
||||||
$ gpg --quick-add-key "011C E16B D45B 27A5 5BA8 776D FF3E 7D88 647E BCDB" \
|
|
||||||
rsa4096 sign 1y
|
|
||||||
```
|
|
||||||
|
|
||||||
Now create an [encryption subkey](https://www.cs.cornell.edu/courses/cs5430/2015sp/notes/rsa_sign_vs_dec.php):
|
|
||||||
|
|
||||||
```console
|
|
||||||
$ gpg --quick-add-key "011C E16B D45B 27A5 5BA8 776D FF3E 7D88 647E BCDB" \
|
|
||||||
rsa4096 encrypt 1y
|
|
||||||
```
|
|
||||||
|
|
||||||
Finally, create an [authentication subkey](https://superuser.com/questions/390265/what-is-a-gpg-with-authenticate-capability-used-for):
|
|
||||||
|
|
||||||
```console
|
|
||||||
$ gpg --quick-add-key "011C E16B D45B 27A5 5BA8 776D FF3E 7D88 647E BCDB" \
|
|
||||||
rsa4096 auth 1y
|
|
||||||
```
|
|
||||||
|
|
||||||
Let's check the final result:
|
|
||||||
|
|
||||||
```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]
|
|
||||||
```
|
|
||||||
|
|
||||||
# Verify
|
# Verify
|
||||||
|
|
||||||
List the generated secret keys and verify the output:
|
List the generated secret keys and verify the output:
|
||||||
@ -1727,7 +1650,7 @@ $ cp -avi /mnt/encrypted-storage/tmp.XXX $GNUPGHOME
|
|||||||
$ cd $GNUPGHOME
|
$ cd $GNUPGHOME
|
||||||
```
|
```
|
||||||
|
|
||||||
## Switching between two or more Yubikeys.
|
## Switching between two or more Yubikeys
|
||||||
|
|
||||||
When you add a GPG key to a Yubikey using the *keytocard* command, GPG deletes the key from your keyring and adds a *stub* pointing to that exact Yubikey (the stub identifies the GPG KeyID and the Yubikey's serial number).
|
When you add a GPG key to a Yubikey using the *keytocard* command, GPG deletes the key from your keyring and adds a *stub* pointing to that exact Yubikey (the stub identifies the GPG KeyID and the Yubikey's serial number).
|
||||||
|
|
||||||
@ -1861,7 +1784,7 @@ sub 4096R/0x3F29127E79649A3D created: 2017-10-09 expires: 2018-10-09 usage:
|
|||||||
gpg> quit
|
gpg> quit
|
||||||
```
|
```
|
||||||
|
|
||||||
Remove and re-insert YubiKey and check the status:
|
Remove and re-insert YubiKey and verify the status:
|
||||||
|
|
||||||
```console
|
```console
|
||||||
$ gpg --card-status
|
$ gpg --card-status
|
||||||
@ -2942,6 +2865,64 @@ Before you unmount your backup, ask yourself if you should make another one just
|
|||||||
* [`piv-agent`](https://github.com/smlx/piv-agent) is an SSH and GPG agent which you can use with your PIV hardware security device (e.g. a Yubikey).
|
* [`piv-agent`](https://github.com/smlx/piv-agent) is an SSH and GPG agent which you can use with your PIV hardware security device (e.g. a Yubikey).
|
||||||
* [`keytotpm`](https://www.gnupg.org/documentation/manuals/gnupg/OpenPGP-Key-Management.html) is an option to use GnuPG with TPM systems.
|
* [`keytotpm`](https://www.gnupg.org/documentation/manuals/gnupg/OpenPGP-Key-Management.html) is an option to use GnuPG with TPM systems.
|
||||||
|
|
||||||
|
## 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)
|
||||||
|
|
||||||
|
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).
|
||||||
|
|
||||||
|
Generate master key:
|
||||||
|
|
||||||
|
```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
|
||||||
|
```
|
||||||
|
|
||||||
|
Verify the result:
|
||||||
|
|
||||||
|
```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>
|
||||||
|
```
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
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):
|
||||||
|
|
||||||
|
```console
|
||||||
|
$ gpg --quick-add-key "011C E16B D45B 27A5 5BA8 776D FF3E 7D88 647E BCDB" \
|
||||||
|
rsa4096 sign 1y
|
||||||
|
```
|
||||||
|
|
||||||
|
Now create an [encryption subkey](https://www.cs.cornell.edu/courses/cs5430/2015sp/notes/rsa_sign_vs_dec.php):
|
||||||
|
|
||||||
|
```console
|
||||||
|
$ gpg --quick-add-key "011C E16B D45B 27A5 5BA8 776D FF3E 7D88 647E BCDB" \
|
||||||
|
rsa4096 encrypt 1y
|
||||||
|
```
|
||||||
|
|
||||||
|
Finally, create an [authentication subkey](https://superuser.com/questions/390265/what-is-a-gpg-with-authenticate-capability-used-for):
|
||||||
|
|
||||||
|
```console
|
||||||
|
$ gpg --quick-add-key "011C E16B D45B 27A5 5BA8 776D FF3E 7D88 647E BCDB" \
|
||||||
|
rsa4096 auth 1y
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
# Links
|
# Links
|
||||||
|
|
||||||
* https://alexcabal.com/creating-the-perfect-gpg-keypair/
|
* https://alexcabal.com/creating-the-perfect-gpg-keypair/
|
||||||
|
Loading…
Reference in New Issue
Block a user