From 0fb5f47d2e8135721e1b5be9ee9e956af5330fc9 Mon Sep 17 00:00:00 2001 From: Thomas Wolf Date: Thu, 30 Dec 2021 17:49:44 +0100 Subject: sshd: Add README.md for SSH agents Explain SSH agent protocols, what transports are available and how to choose them in ~/.ssh/config. For Windows, add some information on which commonly used SSH agents can be used. Change-Id: I0b08a95654fd76643512606edb1ed74d9980aa85 Signed-off-by: Thomas Wolf --- org.eclipse.jgit.ssh.apache.agent/README.md | 82 +++++++++++++++++++++++++++++ 1 file changed, 82 insertions(+) create mode 100644 org.eclipse.jgit.ssh.apache.agent/README.md (limited to 'org.eclipse.jgit.ssh.apache.agent') diff --git a/org.eclipse.jgit.ssh.apache.agent/README.md b/org.eclipse.jgit.ssh.apache.agent/README.md new file mode 100644 index 0000000000..6d62a2fd81 --- /dev/null +++ b/org.eclipse.jgit.ssh.apache.agent/README.md @@ -0,0 +1,82 @@ +# 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..`, 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 -- cgit v1.2.3