--- /dev/null
+# 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.
\ No newline at end of file
.call();
```
+## Support for SSH agents
+
+There exist two IETF draft RFCs for communication with an SSH agent:
+
+* an older [SSH1 protocol](https://tools.ietf.org/html/draft-ietf-secsh-agent-02) that can deal only with DSA and RSA keys, and
+* a newer [SSH2 protocol](https://tools.ietf.org/html/draft-miller-ssh-agent-04) (from OpenSSH).
+
+JGit only supports the newer OpenSSH protocol.
+
+Communication with an SSH agent can occur over any transport protocol, and different
+SSH agents may use different transports for local communication. JGit provides some
+transports via the [org.eclipse.jgit.ssh.apache.agent](../org.eclipse.jgit.ssh.apache.agent/README.md)
+fragment, which are discovered from `org.eclipse.jgit.ssh.apache` also via the `ServiceLoader` mechanism;
+the SPI (service provider interface) is `org.eclipse.jgit.transport.sshd.agent.ConnectorFactory`.
+
+If such a `ConnectorFactory` implementation is found, JGit may use an SSH agent. If none
+is available, JGit cannot communicate with an SSH agent, and will not attempt to use one.
+
+### SSH configurations for SSH agents
+
+There are several SSH properties that can be used in the `~/.ssh/config` file to configure
+the use of an SSH agent. For the details, see the [OpenBSD ssh-config documentation](https://man.openbsd.org/ssh_config.5).
+
+* **AddKeysToAgent** can be set to `no`, `yes`, or `ask`. If set to `yes`, keys will be added
+ to the agent if they're not yet in the agent. If set to `ask`, the user will be prompted
+ before doing so, and can opt out of adding the key. JGit also supports the additional
+ settings `confirm` and key lifetimes.
+* **IdentityAgent** can be set to choose which SSH agent to use, if there are several running.
+ It can also be set to `none` to explicitly switch off using an SSH agent at all.
+* **IdentitiesOnly** if set to `yes` and an SSH agent is used, only keys from the agent that are
+ also listed in an `IdentityFile` property will be considered. (It'll also switch off trying
+ default key names, such as `~/.ssh/id_rsa` or `~/.ssh/id_ed25519`; only keys listed explicitly
+ will be used.)
+
+### Limitations
+
+As mentioned above JGit only implements the newer OpenSSH protocol. OpenSSH fully implements this,
+but some other SSH agents only offer partial implementations. In particular on Windows, neither
+Pageant nor Win32-OpenSSH implement the `confirm` or lifetime constraints for `AddKeysToAgent`. With
+such SSH agents, these settings should not be used in `~/.ssh/config`. GPG's gpg-agent can be run
+with option `enable_putty_support` and can then be used as a Pageant replacement. gpg-agent appears
+to support these key constraints.
+
+OpenSSH does not implement ed448 keys, and neither does Apache MINA sshd, and hence such keys are
+not supported in JGit if its built-in SSH implementation is used. ed448 or other unsupported keys
+provided by an SSH agent are ignored.
+
## Using a different SSH implementation
To use a different SSH implementation:
projects / jgit.git / commitdiff