@ -13,14 +13,13 @@ If you have a comment or suggestion, please open an [issue](https://github.com/d
* [Entropy](#entropy)
* [Entropy](#entropy)
- [Creating keys](#creating-keys)
- [Creating keys](#creating-keys)
- [Master key](#master-key)
- [Master key](#master-key)
- [Subkeys](#subkeys)
- [Sub-keys](#sub-keys)
* [Signing](#signing)
* [Signing](#signing)
* [Encryption](#encryption)
* [Encryption](#encryption)
* [Authentication](#authentication)
* [Authentication](#authentication)
- [Verify keys](#verify-keys)
- [Verify](#verify)
- [Export keys](#export-keys)
- [Export](#export)
- [Backup keys](#backup-keys)
- [Backup](#backup)
- [Configure YubiKey](#configure-yubikey)
- [Configure Smartcard](#configure-smartcard)
- [Configure Smartcard](#configure-smartcard)
* [Change PIN](#change-pin)
* [Change PIN](#change-pin)
* [Set information](#set-information)
* [Set information](#set-information)
@ -31,10 +30,6 @@ If you have a comment or suggestion, please open an [issue](https://github.com/d
- [Verify card](#verify-card)
- [Verify card](#verify-card)
- [Cleanup](#cleanup)
- [Cleanup](#cleanup)
- [Using keys](#using-keys)
- [Using keys](#using-keys)
- [Import public key](#import-public-key)
* [Trust master key](#trust-master-key)
- [Insert YubiKey](#insert-yubikey)
- [Verifying signature](#verifying-signature)
- [SSH](#ssh)
- [SSH](#ssh)
* [Create configuration](#create-configuration)
* [Create configuration](#create-configuration)
* [Replace agents](#replace-agents)
* [Replace agents](#replace-agents)
@ -64,7 +59,7 @@ You will also need several small storage devices for booting a live image, creat
# Verify YubiKey
# 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) 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.
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).
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).
@ -298,9 +293,9 @@ Disable networking for the remainder of the setup.
# Master key
# 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.
The first key to generate is the master key. It will be used for certification only: to issue sub-keys 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.
**Important** The master key should be kept offline at all times and only accessed to revoke or issue new sub-keys. Keys can also be generated on the YubiKey itself to ensure no other copies exist.
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:
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:
@ -409,7 +404,7 @@ Export the key ID as a [variable](https://stackoverflow.com/questions/1158091/de
$ export KEYID=0xFF3E7D88647EBCDB
$ export KEYID=0xFF3E7D88647EBCDB
```
```
# Subkeys
# Sub-keys
Edit the master key to add sub-keys:
Edit the master key to add sub-keys:
@ -612,7 +607,7 @@ ssb rsa4096/0x3F29127E79649A3D
gpg> save
gpg> save
```
```
# Verify keys
# Verify
List the generated secret keys and verify the output:
List the generated secret keys and verify the output:
@ -640,7 +635,7 @@ The output will display any problems with your key in red text. If everything is
> hokey may warn (orange text) about cross certification for the authentication key. GPG's [Signing Subkey Cross-Certification](https://gnupg.org/faq/subkey-cross-certify.html) documentation has more detail on cross certification, and gpg v2.2.1 notes "subkey <keyid> does not sign and so does not need to be cross-certified". hokey may also indicate a problem (red text) with `Key expiration times: []` on the primary key (see [Note #3](#notes) about not setting an expiry for the primary key).
> hokey may warn (orange text) about cross certification for the authentication key. GPG's [Signing Subkey Cross-Certification](https://gnupg.org/faq/subkey-cross-certify.html) documentation has more detail on cross certification, and gpg v2.2.1 notes "subkey <keyid> does not sign and so does not need to be cross-certified". hokey may also indicate a problem (red text) with `Key expiration times: []` on the primary key (see [Note #3](#notes) about not setting an expiry for the primary key).
# Export keys
# Export
The master key and sub-keys 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 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.
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.
Mount the filesystem and copy the temporary GNUPG directory:
Mount the filesystem and copy the temporary directory with the keyring:
```console
```console
$ doas mkdir /mnt/encrypted-usb
$ doas mkdir /mnt/encrypted-usb
@ -914,7 +912,7 @@ $ doas cp -avi $GNUPGHOME /mnt/encrypted-usb
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.
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
```console
$ doas umount /mnt/encrypted-usb
$ doas umount /mnt/encrypted-usb
@ -924,26 +922,40 @@ $ doas bioctl -d sd3
See [OpenBSD FAQ#14](https://www.openbsd.org/faq/faq14.html#softraidCrypto) for more information.
See [OpenBSD FAQ#14](https://www.openbsd.org/faq/faq14.html#softraidCrypto) for more information.
# Configure YubiKey
Create another partition to store the public key, or skip this step if you plan on uploading it to a key server.
**Note** YubiKey NEO shipped after November 2015 have [all modes enabled](https://www.yubico.com/support/knowledge-base/categories/articles/yubikey-neo-manager/); so this step may be skipped. Older versions of the YubiKey NEO may need to be reconfigured as a composite USB device (HID + CCID) which allows OTPs to be emitted while in use as a SmartCard.
**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.
Plug in YubiKey and configure it with the `ykpersonalize` utility:
```console
```console
$ sudo ykpersonalize -m82
$ doas disklabel -E sd2
Firmware version 4.3.7 Touch level 527 Program sequence 1
Label editor (enter '?' for help at any prompt)
sd2> a b
offset: [32130]
size: [31069710] 10M
FS type: [swap] 4.2BSD
sd2*> w
sd2> q
No label changes.
The USB mode will be set to: 0x82
$ doas newfs sd2b
/dev/rsd2b: 15.7MB in 32096 sectors of 512 bytes
5 cylinder groups of 3.89MB, 249 blocks, 512 inodes each
super-block backups (for fsck -b #) at:
32, 8000, 15968, 23936, 31904,
Commit? (y/n) [n]: y
$ doas mkdir /mnt/public
```
The -m option is the mode command. To see the different modes, enter `ykpersonalize -help`. Mode 82 (in hex) enables the YubiKey NEO as a composite USB device (HID + CCID). Once you have changed the mode, you need to re-boot the YubiKey, so remove and re-insert it. On YubiKey NEO with firmware version 3.3 or higher, you can enable composite USB device with `-m86` instead of `-m82`.
$ doas mount /dev/sd2b /mnt/public
**Windows** Use the [YubiKey NEO Manager](https://www.yubico.com/products/services-software/download/yubikey-neo-manager/) to enable CCID functionality.
$ gpg --armor --export $KEYID | doas tee /mnt/public/$KEYID.txt
-----BEGIN PGP PUBLIC KEY BLOCK-----
[...]
```
# Configure Smartcard
# Configure Smartcard
**Windows** Use the [YubiKey NEO Manager](https://www.yubico.com/products/services-software/download/yubikey-neo-manager/) to enable CCID functionality.
gpg: key 0xFF3E7D88647EBCDB: public key "Dr Duh <doc@duh.to>" imported
gpg: key 0xFF3E7D88647EBCDB: public key "Dr Duh <doc@duh.to>" imported
gpg: Total number processed: 1
gpg: Total number processed: 1
gpg: imported: 1
gpg: imported: 1
```
```
To download the public key from a keyserver:
Or download the public key from a keyserver:
```console
```console
$ gpg --recv $KEYID
$ gpg --recv $KEYID
@ -1237,14 +1255,6 @@ gpg: Total number processed: 1
gpg: imported: 1
gpg: imported: 1
```
```
If you get the error `gpgkeys: HTTP fetch error 1: unsupported protocol` - this means you need to install a special version of curl which supports GPG:
```console
$ sudo apt-get install -y gnupg-curl
```
## Trust master key
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` then option `5`: