s83/YubiKey-Guide
1
0
Fork 0
mirror of https://github.com/drduh/YubiKey-Guide.git synced 2025-06-18 19:22:39 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

Merge pull request #482 from drduh/wip-07apr25

Browse source 
more alert markdown formatting
This commit is contained in:
drduh 2025-04-09 00:53:00 +00:00 • committed by GitHub
commit c341c08c95
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 22 additions and 12 deletions
Download patch file Download diff file Expand all files Collapse all files

34
README.md
View file

@ -512,7 +512,9 @@ Create an **encrypted** backup on portable storage to be kept offline in a secur
The following process is recommended to be repeated several times on multiple portable storage devices, as they are likely to fail over time. As an additional backup measure, [Paperkey](https://www.jabberwocky.com/software/paperkey/) can be used to make a physical copy of key materials for improved durability. The following process is recommended to be repeated several times on multiple portable storage devices, as they are likely to fail over time. As an additional backup measure, [Paperkey](https://www.jabberwocky.com/software/paperkey/) can be used to make a physical copy of key materials for improved durability.
**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. > [!TIP]
> [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**
@ -527,7 +529,7 @@ $ sudo fdisk -l /dev/sdc
Disk /dev/sdc: 14.9 GiB, 15931539456 bytes, 31116288 sectors Disk /dev/sdc: 14.9 GiB, 15931539456 bytes, 31116288 sectors
``` ```
> [!WARNING] > [!CAUTION]
> Confirm the destination (`of`) before issuing the following command - it is destructive! This guide uses `/dev/sdc` throughout, but this value may be different on your system. > Confirm the destination (`of`) before issuing the following command - it is destructive! This guide uses `/dev/sdc` throughout, but this value may be different on your system.
Zero the header to prepare for encryption: Zero the header to prepare for encryption:
@ -695,7 +697,8 @@ See [OpenBSD FAQ#14](https://www.openbsd.org/faq/faq14.html#softraidCrypto) for
# Export public key # Export public key
**Important** Without the public key, it will **not** be possible to use GnuPG to decrypt nor sign messages. However, YubiKey can still be used for SSH authentication. > [!IMPORTANT]
> Without the public key, it will **not** be possible to use GnuPG to decrypt/sign messages. However, YubiKey can still be used for SSH authentication.
Connect another portable storage device or create a new partition on the existing one. Connect another portable storage device or create a new partition on the existing one.
@ -854,7 +857,8 @@ Run `gpg --card-status` to verify results (*Login data* field).
# Transfer Subkeys # Transfer Subkeys
**Important** Transferring keys to YubiKey is a one-way operation which converts the on-disk key into a stub making it no longer usable to transfer to subsequent YubiKeys. Ensure a backup was made before proceeding. > [!IMPORTANT]
> Transferring keys to YubiKey is a one-way operation which converts the on-disk key into a stub making it no longer usable to transfer to subsequent YubiKeys. Ensure a backup was made before proceeding.
The Certify key passphrase and Admin PIN are required to transfer keys. The Certify key passphrase and Admin PIN are required to transfer keys.
@ -1213,9 +1217,11 @@ cd ~/.gnupg
wget https://raw.githubusercontent.com/drduh/config/main/gpg-agent.conf wget https://raw.githubusercontent.com/drduh/config/main/gpg-agent.conf
``` ```
**Important** The `cache-ttl` options do **not** apply when using YubiKey as a smart card, because the PIN is [cached by the smart card itself](https://dev.gnupg.org/T3362). To clear the PIN from cache (equivalent to `default-cache-ttl` and `max-cache-ttl`), remove YubiKey, or set `forcesig` when editing the card to be prompted for the PIN each time. > [!NOTE]
> `cache-ttl` options do **not** apply when using YubiKey as a smart card, because the PIN is [cached by the smart card itself](https://dev.gnupg.org/T3362). To clear the PIN from cache (equivalent to `default-cache-ttl` and `max-cache-ttl`), remove YubiKey, or set `forcesig` when editing the card to be prompted for the PIN each time.
**Tip** Set `pinentry-program` to `/usr/bin/pinentry-gnome3` for a GUI-based prompt. > [!TIP]
> Set `pinentry-program` to `/usr/bin/pinentry-gnome3` for a GUI-based prompt.
**macOS** **macOS**
@ -1503,7 +1509,8 @@ debug1: Authentication succeeded (publickey).
[...] [...]
``` ```
**Tip** To make multiple connections or securely transfer many files, use the [ControlMaster](https://en.wikibooks.org/wiki/OpenSSH/Cookbook/Multiplexing) ssh option. > [!TIP]
> To enable multiple connections, use the [ControlMaster](https://en.wikibooks.org/wiki/OpenSSH/Cookbook/Multiplexing) SSH option.
### Import SSH keys ### Import SSH keys
@ -1611,7 +1618,7 @@ Configure a signing key:
git config --global user.signingkey $KEYID git config --global user.signingkey $KEYID
``` ```
**Important** The `user.email` option must match the email address associated with the PGP identity. Configure the `user.email` option to match the email address associated with the PGP identity.
To sign commits or tags, use the `-S` option. To sign commits or tags, use the `-S` option.
@ -1683,7 +1690,7 @@ extra-socket /run/user/1000/gnupg/S.gpg-agent.extra
> [!IMPORTANT] > [!IMPORTANT]
> The pinentry program starts on the *local* host, not remote. > The pinentry program starts on the *local* host, not remote.
**Important** Any pinentry program except `pinentry-tty` or `pinentry-curses` may be used. This is because local `gpg-agent` may start headlessly (by systemd without `$GPG_TTY` set locally telling which tty it is on), thus failed to obtain the pin. Errors on the remote may be misleading saying that there is *IO Error*. (Yes, internally there is actually an *IO Error* since it happens when writing to/reading from tty while finding no tty to use, but for end users this is not friendly.) Any pinentry program except `pinentry-tty` or `pinentry-curses` may be used. This is because local `gpg-agent` may start headlessly (by systemd without `$GPG_TTY` set locally telling which tty it is on), thus failed to obtain the pin. Errors on the remote may be misleading saying that there is *IO Error*. (Yes, internally there is actually an *IO Error* since it happens when writing to/reading from tty while finding no tty to use, but for end users this is not friendly.)
See [Issue 85](https://github.com/drduh/YubiKey-Guide/issues/85) for more information and troubleshooting. See [Issue 85](https://github.com/drduh/YubiKey-Guide/issues/85) for more information and troubleshooting.
@ -1745,13 +1752,15 @@ YubiKey can be used to decrypt and sign emails and attachments using [Thunderbir
Follow [instructions on the mozilla wiki](https://wiki.mozilla.org/Thunderbird:OpenPGP:Smartcards#Configure_an_email_account_to_use_an_external_GnuPG_key) to setup your YubiKey with your thunderbird client using the external gpg provider. Follow [instructions on the mozilla wiki](https://wiki.mozilla.org/Thunderbird:OpenPGP:Smartcards#Configure_an_email_account_to_use_an_external_GnuPG_key) to setup your YubiKey with your thunderbird client using the external gpg provider.
**Important** Thunderbird [fails](https://github.com/drduh/YubiKey-Guide/issues/448) to decrypt emails if the ASCII `armor` option is enabled in your `~/.gnupg/gpg.conf`. If you see the error `gpg: [don't know]: invalid packet (ctb=2d)` or `message cannot be decrypted (there are unknown problems with this encrypted message)` simply remove this option from your config file. > [!NOTE]
> Thunderbird will [fail](https://github.com/drduh/YubiKey-Guide/issues/448) to decrypt emails if the ASCII `armor` option is enabled in `gpg.conf`. If you see the error `gpg: [don't know]: invalid packet (ctb=2d)` or `message cannot be decrypted (there are unknown problems with this encrypted message)` simply remove this option.
### Mailvelope ### Mailvelope
[Mailvelope](https://www.mailvelope.com/en) allows YubiKey to be used with Gmail and others. [Mailvelope](https://www.mailvelope.com/en) allows YubiKey to be used with Gmail and others.
**Important** Mailvelope [does not work](https://github.com/drduh/YubiKey-Guide/issues/178) with the `throw-keyids` option set in `gpg.conf` > [!NOTE]
> Mailvelope [does not work](https://github.com/drduh/YubiKey-Guide/issues/178) with the `throw-keyids` option set in `gpg.conf`
On macOS, install gpgme using Homebrew: On macOS, install gpgme using Homebrew:
@ -1791,7 +1800,8 @@ Edit the file to enable options `pgp_default_key`, `pgp_sign_as` and `pgp_autosi
`source` the file in `muttrc` `source` the file in `muttrc`
**Important** `pinentry-tty` set as the pinentry program in `gpg-agent.conf` is reported to cause problems with Mutt TUI, because it uses curses. It is recommended to use `pinentry-curses` or other graphic pinentry program instead. > [!NOTE]
> `pinentry-tty` set as the pinentry program (in `gpg-agent.conf`) is reported to cause problems with Mutt TUI, because it uses curses; use `pinentry-curses` or other graphic pinentry program instead.
## Keyserver ## Keyserver