913e6cf3f6
Bump the version numbers in pom.xml and in MANIFESTs, and in the bazel WORKSPACE file. Update the target platforms. Remove work-arounds in org.eclipse.jgit.ssh.apache that are no longer necessary. The release notes for Apache MINA sshd are at [1]. [1] https://github.com/apache/mina-sshd/blob/master/docs/changes/2.10.0.md Bug: 581770 Change-Id: Id27e73e9712b7865353c9b32b5b768f6e998b05e Signed-off-by: Thomas Wolf <twolf@apache.org> |
||
---|---|---|
.. | ||
.settings | ||
META-INF | ||
resources | ||
src/org/eclipse/jgit | ||
.classpath | ||
.fbprefs | ||
.gitignore | ||
.project | ||
BUILD | ||
README.md | ||
about.html | ||
build.properties | ||
plugin.properties | ||
pom.xml |
README.md
JGit SSH support via Apache MINA sshd
This bundle provides an implementation of git transport over SSH implemented via Apache MINA sshd.
Service registration
This bundle declares a service for the java.util.ServiceLoader
for interface
org.eclipse.jgit.transport.ssh.SshSessionFactory
. The core JGit bundle uses the service
loader to pick up an implementation of that interface.
Note that JGit simply uses the first SshSessionFactory
provided by the ServiceLoader
.
If the service loader cannot find the session factory, either ensure that the service
declaration is on the Classpath of bundle org.eclipse.jgit
, or set the factory explicitly
(see below).
In an OSGi environment, one might need a service loader bridge, or have a little OSGi
fragment for bundle org.eclipse.jgit
that puts the right service declaration onto the
Classpath of that bundle. (OSGi fragments become part of the Classpath of their host
bundle.)
Configuring an SSH implementation for JGit
The simplest way to set an SSH implementation for JGit is to install it globally via
SshSessionFactory.setInstance()
. This instance will be used by JGit for all SSH
connections by default.
It is also possible to set the SSH implementation individually for any git command
that needs a transport (TransportCommand
) via a org.eclipse.jgit.api.TransportConfigCallback
.
To do so, set the wanted SshSessionFactory
on the SSH transport, like:
SshSessionFactory customFactory = ...; // Get it from wherever
FetchCommand fetch = git.fetch()
.setTransportConfigCallback(transport -> {
if (transport instanceof SshTransport) {
((SshTransport) transport).setSshSessionFactory(customFactory);
}
})
...
.call();
Support for SSH agents
There exist two IETF draft RFCs for communication with an SSH agent:
- an older SSH1 protocol that can deal only with DSA and RSA keys, and
- a newer SSH2 protocol (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
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.
- AddKeysToAgent can be set to
no
,yes
, orask
. If set toyes
, keys will be added to the agent if they're not yet in the agent. If set toask
, the user will be prompted before doing so, and can opt out of adding the key. JGit also supports the additional settingsconfirm
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 anIdentityFile
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:
- Do not include this bundle in your product.
- Include the bundle of the alternate implementation.
- If the service loader finds the alternate implementation, nothing more is needed.
- Otherwise ensure the service declaration from the other bundle is on the Classpath of bundle
org.eclipse.jgit
, - or set the
SshSessionFactory
for JGit explicitly (see above).
Using an external SSH executable
JGit has built-in support for not using any Java SSH implementation but an external SSH executable. To use an external SSH executable, set environment variable GIT_SSH to the path of the executable. JGit will create a sub-process to run the executable and communicate with this sub-process to perform the git operation.