| # JGit SSH agent transport support for Apache MINA sshd | |
| This bundle provides optional support for communicating with an SSH agent | |
| for SSH or SFTP authentication. It is an OSGi fragment for bundle | |
| [org.eclipse.jgit.ssh.apache](../org.eclipse.jgit.ssh.apache/README.md), | |
| and it provides transports for local communication with SSH agents. | |
| ## Supported SSH agent transports | |
| ### Linux, OS X, BSD | |
| On Linux, OS X, and BSD, the only transport mechanism supported is the usual | |
| communication via a Unix domain socket. This is the only protocol the OpenSSH | |
| SSH agent supports. A Unix domain socket appears as a special file in the file | |
| system; this file name is typically available in the environment variable | |
| `SSH_AUTH_SOCK`. | |
| The SSH config `IdentityAgent` can be set to this socket filename to specify | |
| exactly which Unix domain socket to use, or it can be set to `SSH_AUTH_SOCK` | |
| to use the value from that environment variable. If `IdentityAgent` is not set | |
| at all, JGit uses `SSH_AUTH_SOCK` by default. If the variable is not set, no | |
| SSH agent will be used. `IdentityAgent` can also be set to `none` to not use | |
| any SSH agent. | |
| ### Windows | |
| On Windows, two different transports are supported: | |
| * A transport over a Windows named pipe. This is used by Win32-OpenSSH, and is available for Pageant since version 0.75. | |
| * A Pageant-specific legacy transport via shared memory; useful for Pageant and GPG's gpg-agent. | |
| Possible settings of `IdentityAgent` to select a particular transport are | |
| * `//./pipe/openssh-ssh-agent`: the Windows named pipe of Win32-OpenSSH. | |
| * `//./pageant`: the shared-memory mechanism of Pageant. | |
| * `none`: do not use any SSH agent. | |
| * `//./pipe/<any_valid_pipe_name>`: use a specific Windows named pipe. | |
| The default transport on Windows if `IdentityAgent` is not set at all is the | |
| Pageant shared-memory transport. Environment variable `SSH_AUTH_SOCK` needs | |
| not be set for Pageant, and _must not_ be set for Win32-OpenSSH. | |
| It is also possible to use a named pipe as transport for Pageant (as of | |
| version 0.75). Unfortunately, Pageant unnecessarily cryptographically | |
| obfuscates the pipe name, so it is not possible for JGit to determine it | |
| automatically. The pipe name is `pageant.<user name>.<sha256>`, for instance | |
| `pageant.myself.c5687736ba755a70b000955cb191698aed7db221c2b0710199eb1f5298922ab5`. | |
| A user can look up the name by starting Pageant and then running the | |
| command `dir \\.\pipe\\` in a command shell. Once the name is known, setting | |
| `IdentityAgent` to the pipe name as | |
| `//./pipe/pageant.myself.c5687736ba755a70b000955cb191698aed7db221c2b0710199eb1f5298922ab5` | |
| makes JGit use this Windows named pipe for communication with Pageant. | |
| (You can use forward slashes in the `~/.ssh/config` file. SSH config file | |
| parsing has its own rules about backslashes in config files; which are | |
| treated as escape characters in some contexts. With backslashes one would | |
| have to write, e.g., `\\\\.\pipe\openssh-ssh-agent`.) | |
| With these two transport mechanisms, Pageant and Win32-OpenSSH are supported. | |
| As for GPG: the gpg-agent can be configured to emulate ssh-agent (presumably | |
| via a WinSockets2 "Unix domain socket" on Windows) or to emulate Pageant | |
| (using the shared memory mechanism). Running gpg-agent with the | |
| `enable-ssh-support` option is | |
| [reported not to work on Windows](https://dev.gnupg.org/T3883), though. But | |
| the PuTTY emulation in gpg-agent (option `enable-putty-support`) _should_ work, | |
| so it should be possible to use gpg-agent instead of Pageant. | |
| Neither Pageant (as of version 0.76) nor Win32-OpenSSH (as of version 8.6) | |
| support the `confirm` or lifetime constraints for `AddKeysToAgent`. gpg-agent | |
| apparently does, even when communicating over the Pageant shared memory | |
| mechanism. | |
| The ssh-agent from git bash on Windows is currently not supported. It would | |
| need a connector handling Cygwin socket files and the Cygwin handshake over | |
| a TCP stream socket bound to the loopback interface. The Cygwin socket file | |
| _is_ exposed in the Windows file system at %TEMP%\ssh-XXXXXXXXXX\agent.<number>, | |
| but it does not have a fixed name (the X's and the number are variable and | |
| change each time ssh-agent is started). | |
| ## Implementation | |
| The implementation of all transports uses JNA. |