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.pull/225/head
Zenithal
parent
fc6f9eb80d
commit
54f9e8a3f9
129
README.md
129
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:
|
||||
|
|
|
|||
Loading…
Reference in New Issue