Skip steps to create a temporary working directory and a hardened configuration, as they are already part of the image.
Skip steps to create a temporary working directory and a hardened configuration, as they are already part of the image.
@ -415,23 +411,19 @@ EXPIRATION=2026-05-01
Generate a passphrase, which will be used to issue the Certify key and Subkeys.
Generate a passphrase, which will be used to issue the Certify key and Subkeys.
The passphrase is recommended to consist of only uppercase letters and numbers for improved readability. [Diceware](https://secure.research.vt.edu/diceware) is another method for creating strong and memorable passphrases.
The passphrase is recommended to consist of only uppercase letters and numbers for improved readability. [Diceware](https://secure.research.vt.edu/diceware) is another method for creating strong and memorable passphrases.
The following command will generate a strong passphrase while avoiding ambiguous characters:
The following commands will generate and display a strong passphrase which avoids ambiguous characters:
Display the password, then memorize or write it in a secure location, ideally separate from the portable storage device used for key material:
```console
echo $PASS
echo $PASS
```
```
This repository includes a [`passphrase.html`](https://raw.githubusercontent.com/drduh/YubiKey-Guide/master/passphrase.html) file which can be printed and filled out by hand to assist with passphrase transcription. Save the raw file and open it with a browser to print.
Memorize the passphrase or write it in a secure location, ideally separate from the portable storage device used for key material. This repository includes a [`passphrase.html`](https://raw.githubusercontent.com/drduh/YubiKey-Guide/master/passphrase.html) template to help with transcription. Save the raw file, open it with a browser and print. Use a pen or permanent marker to select a letter or number on each row for each character in the passphrase.
Create an **encrypted** backup on portable storage to be kept offline in a secure and durable location.
Create an **encrypted** backup on portable storage to be kept offline in a secure and durable location.
**Tip** The [ext2](https://en.wikipedia.org/wiki/Ext2) filesystem without encryption can be mounted on Linux and OpenBSD. Use [FAT32](https://en.wikipedia.org/wiki/Fat32) or [NTFS](https://en.wikipedia.org/wiki/Ntfs) filesystem for macOS and Windows compatibility instead.
The following process is recommended to be repeated several times on multiple portable storage devices, as they can fail over time. As an additional backup measure, [Paperkey](https://www.jabberwocky.com/software/paperkey/) may be used to make a physical copy of key materials for improved durability.
As an additional backup measure, use [Paperkey](https://www.jabberwocky.com/software/paperkey/) to make a physical copy of materials. See [Linux Kernel Maintainer PGP Guide](https://www.kernel.org/doc/html/latest/process/maintainer-pgp-guide.html#back-up-your-master-key-for-disaster-recovery) for more information.
**Tip** The [ext2](https://en.wikipedia.org/wiki/Ext2) filesystem without encryption can be mounted on Linux and OpenBSD. Use [FAT32](https://en.wikipedia.org/wiki/Fat32) or [NTFS](https://en.wikipedia.org/wiki/Ntfs) filesystem for macOS and Windows compatibility instead.
**Linux**
**Linux**
Attach another portable storage device and check its label:
Attach a portable storage device and check its label, in this case `/dev/sdc`:
```console
```console
$ sudo dmesg | tail
$ sudo dmesg | tail
mmc0: new high speed SDHC card at address a001
usb-storage 3-2:1.0: USB Mass Storage device detected
mmcblk0: mmc0:a001 SS16G 14.8 GiB
sd 2:0:0:0: [sdc] Attached SCSI removable disk
$ sudo fdisk -l /dev/mmcblk0
$ sudo fdisk -l /dev/sdc
Disk /dev/mmcblk0: 14.9 GiB, 15931539456 bytes, 31116288 sectors
Disk /dev/sdc: 14.9 GiB, 15931539456 bytes, 31116288 sectors
Write it with random data to prepare for encryption:
**Warning** Confirm the destination (`of`) before issuing the following command! This guide uses `/dev/sdc` throughout, but this value may differ on your system.
**Note** To set up multiple keys, keep the backup mounted or remember to terminate the GnuPG process before [saving](https://lists.gnupg.org/pipermail/gnupg-users/2016-July/056353.html).
**Note** To provision multiple YubiKeys, keep the backup mounted or remember to terminate the GnuPG process before [saving](https://lists.gnupg.org/pipermail/gnupg-users/2016-July/056353.html).
Unmount, close and disconnect the encrypted volume:
Unmount and close the encrypted volume:
```console
```console
sudo umount /mnt/encrypted-storage/
sudo umount /mnt/encrypted-storage
sudo cryptsetup luksClose secret
sudo cryptsetup luksClose gnupg-secrets
```
```
**OpenBSD**
**OpenBSD**
@ -688,7 +673,7 @@ doas mkdir /mnt/encrypted-storage
doas mount /dev/sd3i /mnt/encrypted-storage
doas mount /dev/sd3i /mnt/encrypted-storage
doas cp -avi $GNUPGHOME /mnt/encrypted-storage
doas cp -av $GNUPGHOME /mnt/encrypted-storage
```
```
**Note** To set up multiple YubiKeys, keep the backup mounted or terminate GnuPG before [saving](https://lists.gnupg.org/pipermail/gnupg-users/2016-July/056353.html).
**Note** To set up multiple YubiKeys, keep the backup mounted or terminate GnuPG before [saving](https://lists.gnupg.org/pipermail/gnupg-users/2016-July/056353.html).
@ -711,36 +696,38 @@ Create another partition on the portable storage device to store the public key,
**Linux**
**Linux**
Provision the portable storage device:
Using the same `/dev/sdc` device as in the previous step:
```console
Create a small (20 Mb is more than enough) partition for storing secret materials:
$ sudo fdisk /dev/mmcblk0
Welcome to fdisk (util-linux 2.36.1).
```console
sudo fdisk /dev/sdc <<EOF
Command (m for help): n
n
Partition number (2-128, default 2):
First sector (53248-30261214, default 53248):
Last sector, +/-sectors or +/-size{K,M,G,T,P} (53248-30261214, default 30261214): +25M
Created a new partition 2 of type 'Linux filesystem' and of size 25 MiB.
Command (m for help): w
+20M
The partition table has been altered.
w
Calling ioctl() to re-read partition table.
EOF
Syncing disks.
```
```
Create a filesystem and export the public key:
Create a filesystem and export the public key:
```console
```console
sudo mkfs.ext2 /dev/mmcblk0p2
sudo mkfs.ext2 /dev/sdc2
sudo mkdir /mnt/public
sudo mkdir /mnt/public
sudo mount /dev/mmcblk0p2 /mnt/public
sudo mount /dev/sdc2 /mnt/public
gpg --armor --export $KEYID | sudo tee /mnt/public/$KEYID-$(date +%F).asc
gpg --armor --export $KEYID | sudo tee /mnt/public/$KEYID-$(date +%F).asc
Entering the *PIN* incorrectly 3 times will cause the PIN to become blocked. It can be unblocked with either the *Admin PIN* or *Reset Code*.
**Warning** Entering the *Admin PIN* or *Reset Code* incorrectly 3 times will destroy data on YubiKey.
Determine the desired PIN values. They can be shorter than the GnuPG identity passphrase due to limited brute-forcing opportunities. The User PIN should be convenient enough to remember for every-day use.
Determine the desired PIN values. They can be shorter than the GnuPG identity passphrase due to limited brute-forcing opportunities. The User PIN should be convenient enough to remember for every-day use.
*PIN* values must be at least 6 characters. *Admin PIN* values must be at least 8 characters. A maximum of 127 ASCII characters are allowed. See the GnuPG documentation on [Managing PINs](https://www.gnupg.org/howtos/card-howto/en/ch03s02.html) for more information.
The *User PIN* must be at least 6 characters and the *Admin PIN* must be at least 8 characters. A maximum of 127 ASCII characters are allowed. See the GnuPG documentation on [Managing PINs](https://www.gnupg.org/howtos/card-howto/en/ch03s02.html) for more information.
Set PINs manually or generate them, for example a 6 digit User PIN and 8 digit Admin PIN:
Set PINs manually or generate them, for example a 6 digit User PIN and 8 digit Admin PIN:
@ -853,7 +836,9 @@ EOF
Remote and re-insert YubiKey.
Remote and re-insert YubiKey.
**Optional** The number of [retry attempts](https://docs.yubico.com/software/yubikey/tools/ykman/OpenPGP_Commands.html#ykman-openpgp-access-set-retries-options-pin-retries-reset-code-retries-admin-pin-retries) can be changed to 5 with:
**Warning** Three incorrect *User PIN* entries will cause it to become blocked and must be unblocked with either the *Admin PIN* or *Reset Code*. Three incorrect *Admin PIN* or *Reset Code* entries will destroy data on YubiKey.
The number of [retry attempts](https://docs.yubico.com/software/yubikey/tools/ykman/OpenPGP_Commands.html#ykman-openpgp-access-set-retries-options-pin-retries-reset-code-retries-admin-pin-retries) can be changed, for example to 5 attempts:
```console
```console
ykman openpgp access set-retries 5 5 5 -f -a $ADMIN_PIN
ykman openpgp access set-retries 5 5 5 -f -a $ADMIN_PIN
@ -950,11 +935,11 @@ A `>` after a tag indicates the key is stored on a smart card.
Verify you have done the following:
Verify you have done the following:
- [ ] Memorized or wrote down Certify key passphrase to a secure and durable location
- [ ] Memorized or wrote down the Certify key passphrase to a secure and durable location
- [ ] Saved the Certify key and Subkeys to encrypted portable storage, to be kept offline
- [ ] Saved the Certify key and Subkeys to encrypted portable storage, to be kept offline
- [ ] Memorized or wrote down passphrase to encrypted volume on portable storage
- [ ] Memorized or wrote down passphrase to encrypted volume on portable storage
- [ ] Exported a copy of the public key where is can be easily accessed later
- [ ] Exported a copy of the public key where is can be easily accessed later
- [ ] Memorized or wrote down YubiKey user and admin PINs, which are unique and changed from default values
- [ ] Memorized or wrote down the User Pin and Admin PIN, which are unique and changed from default values
- [ ] Moved Encryption, Signature and Authentication Subkeys to YubiKey (`gpg -K` shows `ssb>` for 3 Subkeys)
- [ ] Moved Encryption, Signature and Authentication Subkeys to YubiKey (`gpg -K` shows `ssb>` for 3 Subkeys)
Reboot to clear the ephemeral environment and complete setup.
Reboot to clear the ephemeral environment and complete setup.
@ -1012,7 +997,7 @@ doas reboot
Mount the non-encrypted volume with the public key:
Mount the non-encrypted volume with the public key:
```console
```console
doas mount /dev/mmcblk0p2 /mnt
doas mount /dev/sd3i /mnt
```
```
Import it:
Import it:
@ -1203,7 +1188,7 @@ ykman openpgp keys set-touch aut on
To view and adjust policy options:
To view and adjust policy options:
```
```console
ykman openpgp keys set-touch -h
ykman openpgp keys set-touch -h
```
```
@ -1829,21 +1814,14 @@ Neither rotation method is superior and it is up to personal philosophy on ident
To renew or rotate Subkeys, follow the same process as generating keys: boot to a secure environment, install required software and disconnect networking.
To renew or rotate Subkeys, follow the same process as generating keys: boot to a secure environment, install required software and disconnect networking.
Connect the portable storage device with the Certify key and identify the disk label:
Connect the portable storage device with the Certify key and identify the disk label.
```console
$ sudo dmesg | tail
mmc0: new high speed SDHC card at address a001
mmcblk0: mmc0:a001 SS16G 14.8 GiB (ro)
mmcblk0: p1 p2
```
Decrypt and mount the encrypted volume:
Decrypt and mount the encrypted volume:
```console
```console
sudo cryptsetup luksOpen /dev/mmcblk0p1 secret
sudo cryptsetup luksOpen /dev/sdc1 gnupg-secrets
sudo mount /dev/mapper/secret /mnt/encrypted-storage
sudo mount /dev/mapper/gnupg-secrets /mnt/encrypted-storage
```
```
Mount the non-encrypted public partition:
Mount the non-encrypted public partition:
@ -1851,7 +1829,7 @@ Mount the non-encrypted public partition:
```console
```console
sudo mkdir /mnt/public
sudo mkdir /mnt/public
sudo mount /dev/mmcblk0p2 /mnt/public
sudo mount /dev/sdc2 /mnt/public
```
```
Copy the original private key materials to a temporary working directory:
Copy the original private key materials to a temporary working directory:
@ -1859,7 +1837,9 @@ Copy the original private key materials to a temporary working directory:
@ -1938,7 +1918,7 @@ Unmount and close the encrypted volume:
```console
```console
sudo umount /mnt/encrypted-storage
sudo umount /mnt/encrypted-storage
sudo cryptsetup luksClose /dev/mapper/secret
sudo cryptsetup luksClose gnupg-secrets
```
```
Export the updated public key:
Export the updated public key:
@ -1946,7 +1926,7 @@ Export the updated public key:
```console
```console
sudo mkdir /mnt/public
sudo mkdir /mnt/public
sudo mount /dev/mmcblk0p2 /mnt/public
sudo mount /dev/sdc2 /mnt/public
gpg --armor --export $KEYID | sudo tee /mnt/public/$KEYID-$(date +%F).asc
gpg --armor --export $KEYID | sudo tee /mnt/public/$KEYID-$(date +%F).asc
@ -2002,7 +1982,7 @@ Admin PIN: 12345678
1. To switch between YubiKeys, unplug the first YubiKey and restart gpg-agent, ssh-agent and pinentry with `pkill "gpg-agent|ssh-agent|pinentry" ; eval $(gpg-agent --daemon --enable-ssh-support)` then insert the other YubiKey and run `gpg-connect-agent updatestartuptty /bye`
1. To switch between YubiKeys, unplug the first YubiKey and restart gpg-agent, ssh-agent and pinentry with `pkill "gpg-agent|ssh-agent|pinentry" ; eval $(gpg-agent --daemon --enable-ssh-support)` then insert the other YubiKey and run `gpg-connect-agent updatestartuptty /bye`
1. To use YubiKey on multiple computers, import the corresponding public keys. Confirm see YubiKey is visible with `gpg --card-status`, then trust the imported public keys ultimately with `trust` and `5`.`gpg --list-secret-keys` will show the correct and trusted key.
1. To use YubiKey on multiple computers, import the corresponding public keys, then confirm YubiKey is visible with `gpg --card-status`. Trust the imported public keys ultimately with `trust` and `5`, then`gpg --list-secret-keys` will show the correct and trusted key.
drduh
3 months ago