@ -29,15 +29,11 @@ If you have a comment or suggestion, please open an [issue](https://github.com/d
* [Encryption](#encryption-1)
* [Authentication](#authentication-1)
- [Verify card](#verify-card)
- [Export public key](#export-public-key)
- [Cleanup](#cleanup)
- [Using keys](#using-keys)
- [Import public key](#import-public-key)
* [Trust master key](#trust-master-key)
- [Insert YubiKey](#insert-yubikey)
- [Encryption](#encryption-2)
- [Decryption](#decryption)
- [Signing](#signing-2)
- [Verifying signature](#verifying-signature)
- [SSH](#ssh)
* [Create configuration](#create-configuration)
@ -64,70 +60,133 @@ If you have a comment or suggestion, please open an [issue](https://github.com/d
All YubiKeys except the blue "security key" model are compatible with this guide. NEO models are limited to 2048-bit RSA keys. See [Compare YubiKeys](https://www.yubico.com/products/yubikey-hardware/compare-yubikeys/).
Consider purchasing a pair of YubiKeys, programming both, and storing one in a safe secondary location, in case of loss or damage to the first key.
You will also need several small storage devices for booting a live image, creating backups of private and public keys.
# Verify YubiKey
To confirm your 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) and go to [https://www.yubico.com/genuine/](https://www.yubico.com/genuine/). Insert your Yubico device, and click `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`, your device is authentic.
To confirm your 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 your 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`, your device is authentic.
This website verifies the YubiKey's device attestation certificates signed by a set of Yubico CAs, and helps mitigate [supply chain attacks](https://media.defcon.org/DEF%20CON%2025/DEF%20CON%2025%20presentations/DEFCON-25-r00killah-and-securelyfitz-Secure-Tokin-and-Doobiekeys.pdf).
# Live image
It is recommended to generate cryptographic keys and configure YubiKey from a secure environment to minimize exposure. One way to do that is by downloading and booting to a [Debian Live](https://www.debian.org/CD/live/) or [Tails](https://tails.boum.org/index.en.html) image loaded from a USB drive into memory.
It is recommended to generate cryptographic keys and configure YubiKey from a secure operating system and ephemeral environment, such as [Debian Live](https://www.debian.org/CD/live/) or [Tails](https://tails.boum.org/index.en.html).
Download the latest image and verify its integrity:
$ doas dd if=debian-live-9.9.0-amd64-xfce.iso of=/dev/rsd2c bs=4m
465+1 records in
465+1 records out
1951432704 bytes transferred in 139.125 secs (14026448 bytes/sec)
```
Shut down the computer and disconnect any hard drives and unnecessary peripheral devices.
Plug in the USB disk and boot to the live image. Configure networking to continue. If the screen locks, unlock with user/live.
Consider using secure hardware like a ThinkPad X230 running [Coreboot](https://www.coreboot.org/) and cleaned of [Intel ME](https://github.com/corna/me_cleaner).
# Required software
Install several packages required for the following steps:
Boot the live image and configure networking.
**Note** If the screen locks, unlock with credentials: user/live.
Open the terminal and install several required packages:
Download and install [Gpg4Win](https://www.gpg4win.org/) and [PuTTY](https://putty.org).
**Note** You may also need more recent versions of [yubikey-personalization](https://developers.yubico.com/yubikey-personalization/Releases/) and [yubico-c](https://developers.yubico.com/yubico-c/Releases/).
You may also need more recent versions of [yubikey-personalization](https://developers.yubico.com/yubikey-personalization/Releases/) and [yubico-c](https://developers.yubico.com/yubico-c/Releases/).
## Entropy
Generating keys will require a lot of randomness. To check the available bits of entropy available on Linux:
Generating cryptographic keys requires high-quality [randomness](https://www.random.org/randomness/), measured as entropy.
To check the available entropy available on Linux:
```console
$ cat /proc/sys/kernel/random/entropy_avail
849
```
**Optional** A hardware random number generator like [OneRNG](http://onerng.info/onerng/) will increase the speed of entropy generation and possibly its quality. To install and configure OneRNG:
Most operating systems use software-based pseudorandom number generators. A hardware random number generator like [OneRNG](http://onerng.info/onerng/) will [increase the speed](https://lwn.net/Articles/648550/) of entropy generation and possibly the quality.
Plug in the device, then install and configure OneRNG software:
```console
$ sudo apt-get install -y rng-tools at python-gnupg openssl
$ echo "HRNGDEVICE=/dev/ttyACM0" | sudo tee /etc/default/rng-tools
$ sudo atd
$ sudo service rng-tools restart
```
If the service fails to start, kick off `atd` and try again:
Test by emptying `/dev/random` - the light on the device should dim briefly:
```console
$ sudo atd ; sudo service rng-tools restart
$ cat /dev/random >/dev/null
[Press Control-C]
```
Plug in the OneRNG and empty `/dev/random` - the light on the device should dim briefly. Verify the available entropy pool is re-seeded.
Verify the available entropy pool is re-seeded:
```console
$ cat /dev/random >/dev/null
[Control-C]
$ cat /proc/sys/kernel/random/entropy_avail
3049
```
An entropy pool value greater than 3000 is sufficient.
An entropy pool value greater than 2000 is sufficient.
# Creating keys
Create a temporary directory which will be deleted on [reboot](https://en.wikipedia.org/wiki/Tmpfs):
Create a temporary directory which will be cleared on [reboot](https://en.wikipedia.org/wiki/Tmpfs):
```console
$ export GNUPGHOME=$(mktemp -d) ; echo $GNUPGHOME
@ -234,7 +298,9 @@ Disable networking for the remainder of the setup.
# Master key
The first key to generate is the master key. It will be used for certification only - to issue subkeys that are used for encryption, signing and authentication. This master key should be kept offline at all times and only accessed to revoke or issue new subkeys.
The first key to generate is the master key. It will be used for certification only: to issue subkeys 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 subkeys.
You'll be prompted to enter and verify a passphrase - keep it handy as you'll need it throughout. To generate a strong passphrase which could be written down in a hidden or secure place; or memorized:
@ -243,7 +309,11 @@ $ gpg --gen-random -a 0 24
ydOmByxmDe63u7gqx2XI9eDgpvJwibNH
```
Generate a new key with GPG, selecting `(8) RSA (set your own capabilities)`, `Certify`-only and `4096` bit keysize. Do not set the key to expire - see [Note #3](#notes).
On Linux, select the password with your mouse to copy it to the clipboard and paste using the middle mouse button or `Shift`-`Insert`.
Generate a new key with GPG, selecting `(8) RSA (set your own capabilities)`, `Certify` capability only and `4096` bit key size.
Do not set the master key to expire - see [Note #3](#notes).
```console
$ gpg --expert --full-generate-key
@ -302,7 +372,11 @@ Please specify how long the key should be valid.
Key is valid for? (0) 0
Key does not expire at all
Is this correct? (y/N) y
```
Select a name and email address - neither has to be valid nor existing.
```console
GnuPG needs to construct a user ID to identify your key.
Real name: Dr Duh
@ -317,21 +391,18 @@ 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.
Note that this key cannot be used for encryption. You may want to use
the command "--edit-key" to generate a subkey for this purpose.
As of GPG [version 2.1](https://www.gnupg.org/faq/whats-new-in-2.1.html#autorev), a revocation certificate is automatically generated at this time.
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:
**Optional** Add any additional identities or email addresses now using the `adduid` command.
Add any additional identities or email addresses you wish to associate using the `adduid` command.
To 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):
**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):
```console
$ gpg --export $KEYID | hokey lint
@ -571,7 +642,7 @@ The output will display any problems with your key in red text. If everything is
# Export keys
The Master and subkeys will be encrypted with your passphrase when exported.
The master key and sub-keys will be encrypted with your passphrase when exported.
Once GPG keys are moved to YubiKey, they cannot be extracted again!
Make sure you have made an **encrypted** backup before proceeding. An encrypted USB drive or container can be made using [VeraCrypt](https://www.veracrypt.fr/en/Downloads.html).
Also consider using a [paper copy](https://www.jabberwocky.com/software/paperkey/) of the keys as an additional backup measure.
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.
**Linux**
Attach a USB disk and check its label:
Attach another external storage device and check its label:
```console
$ sudo dmesg | tail
scsi8 : usb-storage 2-1:1.0
usbcore: registered new interface driver usb-storage
Keep the backup mounted if you plan on setting up two or more keys as `keytocard`**will [delete](https://lists.gnupg.org/pipermail/gnupg-users/2016-July/056353.html) the local copy** on save.
Otherwise, unmount and disconnected the encrypted USB disk:
Otherwise, unmount and disconnected the encrypted volume:
```console
$ sudo umount /mnt
$ sudo umount /mnt/encrypted-usb
$ sudo cryptsetup luksClose usb
```
Create another partition to store the public key, or skip this step if you plan on uploading it to a key server.
**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.
```console
$ sudo fdisk /dev/sdb
Command (m for help): n
Partition type
p primary (1 primary, 0 extended, 3 free)
e extended (container for logical partitions)
Select (default p):
Partition number (2-4, default 2):
First sector (22528-31116287, default 22528):
Last sector, +sectors or +size{K,M,G,T,P} (22528-31116287, default 31116287): +10M
Created a new partition 2 of type 'Linux' and of size 10 MiB.
Command (m for help): w
The partition table has been altered.
Calling ioctl() to re-read partition table.
Syncing disks.
$ sudo mkfs.ext2 /dev/sdb2
Creating filesystem with 10240 1k blocks and 2560 inodes
Superblock backups stored on blocks:
8193
Allocating group tables: done
Writing inode tables: done
Writing superblocks and filesystem accounting information: done
$ sudo mkdir /mnt/public
$ sudo mount /dev/sdb2 /mnt/public/
$ gpg --armor --export $KEYID | sudo tee /mnt/public/$KEYID.txt
After some time, the public key will to propagate to [other](https://pgp.key-server.io/pks/lookup?search=doc%40duh.to&fingerprint=on&op=vindex) [servers](https://pgp.mit.edu/pks/lookup?search=doc%40duh.to&op=index).
**OpenBSD**
Attach a USB disk and determine its label:
@ -753,7 +878,7 @@ Re-type passphrase:
softraid0: CRYPTO volume attached as sd3
```
Make an `i` partition, then make and mount the filesystem:
Create an `i` partition, then create and mount the filesystem:
```console
$ doas fdisk -iy sd3
@ -846,7 +971,7 @@ General key info..: [none]
## Change PIN
The default PIN is `123456` and default Admin PIN (PUK) is `12345678`. CCID-mode PINs can be up to 127 ASCII characters long.
The default PIN is `123456` and default Admin PIN (PUK) is `12345678`. CCID-mode PINs can be up to 127 ASCII characters.
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.
@ -899,7 +1024,7 @@ Language preferences: en
gpg/card> login
Login data (account name): doc@duh.to
gpg/card> [Press Enter]
gpg/card> list
Application ID ...: D2760001240102010006055532110000
Version ..........: 2.1
@ -1034,7 +1159,7 @@ gpg> save
# Verify card
Verify the subkeys have moved to YubiKey as indicated by `ssb>`:
Verify the sub-keys have been moved to YubiKey as indicated by `ssb>`:
Mount another USB disk to copy the *public* key, or save it somewhere where it can be easily accessed later.
**Important** Without importing 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.
After some time, the public key will to propagate to [other](https://pgp.key-server.io/pks/lookup?search=doc%40duh.to&fingerprint=on&op=vindex) [servers](https://pgp.mit.edu/pks/lookup?search=doc%40duh.to&op=index).
# Cleanup
Ensure you have:
* Saved the Encryption, Signing and Authentication subkeys to YubiKey.
* Saved the encryption, signing and authentication sub-keys to YubiKey.
* Saved the YubiKey PINs which you changed from defaults.
* Saved the password to the Master key.
* Saved a copy of the Master key, subkeys and revocation certificates on an encrypted volume stored offline.
* Saved the password to the master key.
* Saved a copy of the master key, sub-keys and revocation certificates 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.
gpg: Signature made Wed 25 May 2016 00:00:00 AM UTC
gpg: using RSA key 0xBECFA3C1AE191D15
gpg: Good signature from "Dr Duh <doc@duh.to>" [ultimate]
@ -1718,7 +1727,7 @@ And reload the SSH daemon (e.g., `sudo service sshd reload`).
# 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).
1. Programming YubiKey for GPG keys still lets you use its two configurations - [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. 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.
drduh
5 years ago