From ad002122408e5dd483e0a9f3cd8e1f068c610bc9 Mon Sep 17 00:00:00 2001 From: Aaron Young Date: Sun, 10 May 2026 08:59:39 -0400 Subject: [PATCH] Wrap OS-specific instructions in collapsible sections MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Use
/ HTML to make every OS-specific instruction block collapsible. Covers: writing the boot image, installing software, backing up keys, exporting the public key, installing packages, mounting volumes, SSH agent setup, and GitHub configuration — across Linux, Debian/Ubuntu, OpenBSD, macOS, NixOS, Arch, RHEL7, Fedora, Windows, and WSL. Readers no longer need to scroll past irrelevant platform instructions to follow the guide on their OS. All platforms remain discoverable via the labelled summary toggles. --- README.md | 115 +++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 92 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index d0d4784..4eea14a 100644 --- a/README.md +++ b/README.md @@ -132,7 +132,8 @@ See [Verifying authenticity of Debian CDs](https://www.debian.org/CD/verify) for Connect a portable storage device and identify the disk label - this guide uses `/dev/sdc` throughout, but this value may differ on your system: -**Linux** +
+Linux ```console $ sudo dmesg | tail @@ -146,7 +147,10 @@ Copy the Debian image to the device: sudo dd if=debian-live-*-amd64-xfce.iso of=/dev/sdc bs=4M status=progress ; sync ``` -**OpenBSD** +
+ +
+OpenBSD ```console $ dmesg | tail -n2 @@ -159,6 +163,8 @@ $ doas dd if=debian-live-*-amd64-xfce.iso of=/dev/rsd2c bs=4m 1951432704 bytes transferred in 139.125 secs (14026448 bytes/sec) ``` +
+ Power off, remove internal hard drives and all unnecessary devices, such as the wireless card. # Install software @@ -170,7 +176,8 @@ Load the operating system and configure networking. Optional hardening steps rel Open terminal and install required software packages. -**Debian/Ubuntu** +
+Debian/Ubuntu ```console sudo apt update @@ -183,13 +190,19 @@ sudo apt -y install \ yubikey-personalization yubikey-manager ``` -**OpenBSD** +
+ +
+OpenBSD ```console doas pkg_add gnupg pcsc-tools ``` -**macOS** +
+ +
+macOS Download and install [Homebrew](https://brew.sh/) and the following packages: @@ -207,7 +220,10 @@ Or using [MacPorts](https://www.macports.org/install.php), install the following sudo port install gnupg2 yubikey-manager pinentry wget ``` -**NixOS** +
+ +
+NixOS Build an air-gapped NixOS LiveCD image: @@ -253,19 +269,28 @@ qemu-system-x86_64 \ -drive readonly=on,media=cdrom,format=raw,file=result/iso/yubikeyLive.iso ``` -**Arch** +
+ +
+Arch ```console sudo pacman -Syu --needed gnupg pcsclite ccid yubikey-personalization ``` -**RHEL7** +
+ +
+RHEL7 ```console sudo yum install -y gnupg2 pinentry-curses pcsc-lite pcsc-lite-libs gnupg2-smime ``` -**Fedora** +
+ +
+Fedora ```console sudo dnf install --skip-unavailable \ @@ -274,6 +299,8 @@ sudo dnf install --skip-unavailable \ yubikey-personalization-gui yubikey-manager ``` +
+ # Prepare GnuPG Create a temporary directory which will be cleared on [reboot](https://en.wikipedia.org/wiki/Tmpfs) and set it as the GnuPG directory: @@ -550,7 +577,8 @@ The following process is recommended to be repeated several times on multiple po > [ext2](https://en.wikipedia.org/wiki/Ext2) volumes (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) volumes for macOS and Windows compatibility instead. -**Linux** +
+Linux Attach a portable storage device and check its label, in this case `/dev/sdc`: @@ -652,7 +680,10 @@ sudo cryptsetup luksClose gnupg-secrets Repeat the process for any additional storage devices (at least two are recommended). -**OpenBSD** +
+ +
+OpenBSD Attach a USB disk and determine its label: @@ -734,6 +765,8 @@ doas bioctl -d sd3 See [OpenBSD FAQ#14](https://www.openbsd.org/faq/faq14.html#softraidCrypto) for more information. +
+ # Export public key > [!IMPORTANT] @@ -741,7 +774,8 @@ See [OpenBSD FAQ#14](https://www.openbsd.org/faq/faq14.html#softraidCrypto) for Connect another portable storage device or create a new partition on the existing one. -**Linux** +
+Linux Using the same `/dev/sdc` device as in the previous step, create a small (at least 20 Mb is recommended) partition for storing materials: @@ -775,7 +809,10 @@ Unmount and remove the storage device: sudo umount /mnt/public ``` -**OpenBSD** +
+ +
+OpenBSD ```console $ doas disklabel -E sd2 @@ -807,6 +844,8 @@ Unmount and remove the storage device: doas umount /mnt/public ``` +
+ # Configure YubiKey Connect YubiKey and confirm its status: @@ -1009,7 +1048,8 @@ echo "disable-ccid" >>scdaemon.conf Install the required packages: -**Debian/Ubuntu** +
+Debian/Ubuntu ```console sudo apt update @@ -1017,7 +1057,10 @@ sudo apt update sudo apt install -y gnupg gnupg-agent scdaemon pcscd ``` -**Arch** +
+ +
+Arch ```console sudo pacman -S --needed gnupg pcsc-tools @@ -1025,7 +1068,10 @@ sudo pacman -S --needed gnupg pcsc-tools sudo systemctl enable --now pcscd.service ``` -**macOS** +
+ +
+macOS ```console brew install gnupg @@ -1037,7 +1083,10 @@ Or using MacPorts sudo port install gnupg2 pcsc-tools ``` -**OpenBSD** +
+ +
+OpenBSD ```console doas pkg_add gnupg pcsc-tools @@ -1047,9 +1096,12 @@ doas rcctl enable pcscd doas reboot ``` +
+ Mount the non-encrypted volume with the public key: -**Debian/Ubuntu** +
+Debian/Ubuntu ```console sudo mkdir -p /mnt/public @@ -1057,7 +1109,10 @@ sudo mkdir -p /mnt/public sudo mount /dev/sdc2 /mnt/public ``` -**OpenBSD** +
+ +
+OpenBSD ```console doas mkdir -p /mnt/public @@ -1065,6 +1120,8 @@ doas mkdir -p /mnt/public doas mount /dev/sd3i /mnt/public ``` +
+ Import the public key: ```console @@ -1285,7 +1342,8 @@ wget https://raw.githubusercontent.com/drduh/YubiKey-Guide/master/config/gpg-age > [!TIP] > Set `pinentry-program` to `/usr/bin/pinentry-gnome3` for a GUI-based prompt. -**macOS** +
+macOS Install pinentry with `brew install pinentry-mac` or `sudo port install pinentry` then edit `gpg-agent.conf` to set the `pinentry-program` path to: @@ -1360,7 +1418,10 @@ launchctl load $HOME/Library/LaunchAgents/gnupg.gpg-agent-symlink.plist Reboot to activate changes. -**Windows** +
+ +
+Windows Windows can already have some virtual smart card readers installed, like the one provided for Windows Hello. To verify YubiKey is the correct one used by scdaemon, add it to its configuration. @@ -1424,7 +1485,10 @@ Create a shortcut that points to `gpg-connect-agent /bye` and place it in the st PuTTY can now be used for public-key SSH authentication. When the server asks for public-key verification, PuTTY will forward the request to GnuPG, which will prompt for a PIN to authorize the operation. -**WSL** +
+ +
+WSL The goal is to configure SSH client inside WSL work together with the Windows agent, such as gpg-agent.exe. @@ -1494,6 +1558,8 @@ polkit.addRule(function(action, subject) { }); ``` +
+ ### Replace agents To launch `gpg-agent` for use by SSH, use the `gpg-connect-agent /bye` or `gpgconf --launch gpg-agent` commands. @@ -1706,7 +1772,8 @@ git config --global commit.gpgsign true git config --global tag.gpgSign true ``` -**Windows** +
+Windows Configure authentication: @@ -1718,6 +1785,8 @@ git config --global gpg.program 'C:\Program Files (x86)\GnuPG\bin\gpg.exe' Then update the repository URL to `git@github.com:USERNAME/repository` +
+ ## GnuPG agent forwarding YubiKey can be used sign git commits and decrypt files on remote hosts with GnuPG Agent Forwarding. To ssh through another network, especially to push to/pull from GitHub using ssh, see [Remote Machines (SSH Agent forwarding)](#ssh-agent-forwarding).