Add details to GPG-Agent forward; Alter structure

GPG Agent forwarding has a broader usage, not only
limited to ssh-agent forwarding.

In this commit gpg-agent forwarding is raised as a
separate section as it can not be contained by #SSH
any longer.

More details are added for gpg-agent forwarding, including
some important notes taken from practice and analysis.

For ssh-agent forward, older method are contained, and new
method will be included as framework has been structured.

1 files changed, 73 insertions, 56 deletions

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/<user>/.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/<user>/.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: