diff --git a/README.md b/README.md index 47f5c0b..69ed792 100644 --- a/README.md +++ b/README.md @@ -55,8 +55,7 @@ If you have a comment or suggestion, please open an [Issue](https://github.com/d * [(Optional) Save public key for identity file configuration](#optional-save-public-key-for-identity-file-configuration) * [Connect with public key authentication](#connect-with-public-key-authentication) * [Import SSH keys](#import-ssh-keys) - * [Remote Machines (Agent Forwarding)](#remote-machines-agent-forwarding) - + [Steps for older distributions](#steps-for-older-distributions) + * [Remote machines (SSH Agent Forwarding)](#remote-machines-ssh-agent-forwarding) * [GitHub](#github) * [OpenBSD](#openbsd-1) * [Windows](#windows-1) @@ -64,6 +63,8 @@ If you have a comment or suggestion, please open an [Issue](https://github.com/d - [Prerequisites](#prerequisites) - [WSL configuration](#wsl-configuration) - [Remote host configuration](#remote-host-configuration) +- [Remote Machines (Agent Forwarding)](#remote-machines-agent-forwarding) + * [Steps for older distributions](#steps-for-older-distributions) - [Using Multiple Keys](#using-multiple-keys) - [Require touch](#require-touch) - [Email](#email) @@ -2070,66 +2071,15 @@ $ ssh-add -E md5 -l When using the key `pinentry` will be invoked to request the key's passphrase. The passphrase will be cached for up to 10 minutes idle time between uses, to a maximum of 2 hours. -## Remote Machines (Agent Forwarding) +## Remote Machines (SSH Agent Forwarding) **Note** SSH Agent Forwarding can [add additional risk](https://matrix.org/blog/2019/05/08/post-mortem-and-remediations-for-apr-11-security-incident/#ssh-agent-forwarding-should-be-disabled) - proceed with caution! -To use YubiKey to sign a git commit on a remote host, or ssh through another network, configure and use Agent Forwarding. - -To do this, you need access to the remote machine and the YubiKey has to be set up on the host machine. - -On the remote machine, edit `/etc/ssh/sshd_config` to set `StreamLocalBindUnlink yes` - -**Optional** If you do not have root access to the remote machine to edit `/etc/ssh/sshd_config`, you will need to remove the socket on the remote machine before forwarding works. For example, `rm /run/user/1000/gnupg/S.gpg-agent`. Further information can be found on the [AgentForwarding GNUPG wiki page](https://wiki.gnupg.org/AgentForwarding). - -Import public keys to the remote machine. This can be done by fetching from a keyserver. On the local machine, copy the public keyring to the remote machine: - -```console -$ scp ~/.gnupg/pubring.kbx remote:~/.gnupg/ -``` +### Use ssh-agent You should now be able use `ssh -A remote` on the _local_ machine to log into _remote_, and should then be able to use YubiKey as if it were connected to the remote machine. For example, using e.g. `ssh-add -l` on that remote machine should show the public key from the YubiKey (note `cardno:`). (If you don't want to have to remember to use `ssh -A`, you can use `ForwardAgent yes` in `~/.ssh/config`. As a security best practice, always use `ForwardAgent yes` only for a single `Hostname`, never for all servers.) -On modern distributions, such as Fedora 30, there is typically no need to also set `RemoteForward` in `~/.ssh/config` as detailed in the next chapter, because the right thing actually happens automatically. - - -### Steps for older distributions - -On the local machine, run: - -```console -$ gpgconf --list-dirs agent-extra-socket -``` - -This should return a path to agent-extra-socket - `/run/user/1000/gnupg/S.gpg-agent.extra` - though on older Linux distros (and macOS) it may be `/home//.gnupg/S/gpg-agent.extra` - -Find the agent socket on the **remote** machine: - -```console -$ gpgconf --list-dirs agent-socket -``` - -This should return a path such as `/run/user/1000/gnupg/S.gpg-agent` - -Finally, enable agent forwarding for a given machine by adding the following to the local machine's ssh config file `~/.ssh/config` (your agent sockets may be different): - -``` -Host - Hostname remote-host.tld - ForwardAgent yes - RemoteForward /run/user/1000/gnupg/S.gpg-agent /run/user/1000/gnupg/S.gpg-agent.extra - # RemoteForward [remote socket] [local socket] -``` - -If you're still having problems, it may be necessary to edit `gpg-agent.conf` file on both the remote and local machines to add the following information: - -``` -enable-ssh-support -pinentry-program /usr/bin/pinentry-curses -extra-socket /run/user/1000/gnupg/S.gpg-agent.extra -``` - -See [Issue #85](https://github.com/drduh/YubiKey-Guide/issues/85) for more information and troubleshooting. +### Use S.gpg-agent.ssh ## GitHub @@ -2271,6 +2221,73 @@ On the remote host, type `ssh-add -l` - if you see the ssh key, that means forwa **Note** Agent forwarding may be chained through multiple hosts - just follow the same [protocol](#remote-host-configuration) to configure each host. +# Remote Machines (Agent Forwarding) + +This section is different from ssh-agent forwarding in [SSH](#ssh) as gpg-agent forwarding has a broader usage, not only limited to ssh. + +To use YubiKey to sign a git commit on a remote host, or signing email/decrypt files on a remote host, configure and use GPG Agent Forwarding. To ssh through another network, especially to push to/pull from GitHub using ssh, see [Remote Machines](#SSH Agent Forwarding) for more info. + +To do this, you need access to the remote machine and the YubiKey has to be set up on the host machine. + +After gpg-agent forwarding, it is nearly the same as if YubiKey was inserted in the remote. Hence configurations except `gpg-agent.conf` for the remote can be the same as those for the local. + +**Important** `gpg-agent.conf` for the remote is of no use, hence `$GPG_TTY` is of no use too for the remote. The mechanism is that after forwarding, remote `gpg` directly communicates with `S.gpg-agent` without *starting* `gpg-agent` on the remote. + +On the remote machine, edit `/etc/ssh/sshd_config` to set `StreamLocalBindUnlink yes` + +**Optional** If you do not have root access to the remote machine to edit `/etc/ssh/sshd_config`, you will need to remove the socket (located at `gpgconf --list-dir agent-socket`) on the remote machine before forwarding works. For example, `rm /run/user/1000/gnupg/S.gpg-agent`. Further information can be found on the [AgentForwarding GNUPG wiki page](https://wiki.gnupg.org/AgentForwarding). + +Import public keys to the remote machine. This can be done by fetching from a keyserver. On the local machine, copy the public keyring to the remote machine: + +```console +$ scp ~/.gnupg/pubring.kbx remote:~/.gnupg/ +``` + +On modern distributions, such as Fedora 30, there is typically no need to also set `RemoteForward` in `~/.ssh/config` as detailed in the next chapter, because the right thing actually happens automatically. + +If any error happens (or there is no `gpg-agent.socket` in the remote) for modern distributions, you may go through the configuration steps in the next section. + +## Steps for older distributions + +On the local machine, run: + +```console +$ gpgconf --list-dirs agent-extra-socket +``` + +This should return a path to agent-extra-socket - `/run/user/1000/gnupg/S.gpg-agent.extra` - though on older Linux distros (and macOS) it may be `/home//.gnupg/S/gpg-agent.extra` + +Find the agent socket on the **remote** machine: + +```console +$ gpgconf --list-dirs agent-socket +``` + +This should return a path such as `/run/user/1000/gnupg/S.gpg-agent` + +Finally, enable agent forwarding for a given machine by adding the following to the local machine's ssh config file `~/.ssh/config` (your agent sockets may be different): + +``` +Host + Hostname remote-host.tld + StreamLocalBindUnlink yes + RemoteForward /run/user/1000/gnupg/S.gpg-agent /run/user/1000/gnupg/S.gpg-agent.extra + # RemoteForward [remote socket] [local socket] +``` + +If you're still having problems, it may be necessary to edit `gpg-agent.conf` file on the *local* machines to add the following information: + +``` +pinentry-program /usr/bin/pinentry-gtk-2 +extra-socket /run/user/1000/gnupg/S.gpg-agent.extra +``` + +**Note** The pinentry program starts on *local* machine, not remote. Hence when there are needs to enter the pin you need to find the prompt on local machine. + +**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 *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. + # Using Multiple Keys To use a single identity with multiple YubiKeys - or to replace a lost card with another - issue this command to switch keys: