Skip to content

Files

Latest commit

 

History

History

org.eclipse.jgit.ssh.apache

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:

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, 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 and for which the public key is available in a corresponding *.pub file 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.

PKCS#11 support

JGit supports using PKCS#11 HSMs (Hardware Security Modules) such as YubiKey PIV for SSH authentication.

Using such a PKCS#11 token for SSH authentication can be configured in ~/.ssh/config with a configuration

  PCKS11Provider /absolute/path/to/vendor/library.so

instead of or in addition to IdentityFile or IdentityAgent. PKCS#11 keys are considered before keys from an SSH agent. If IdentitiesOnly is also set, only keys listed in IdentityFile for which the public key is available in a corresponding *.pub file are considered.

If PKCS11Provider is not set, or is set to the value none, no PKCS#11 library is used.

This is all as in OpenSSH.

Keys from PKCS#11 tokens are never added to an SSH agent; the AddKeysToAgent configuration has no effect for PKCS#11 keys in JGit. It makes only sense if someone is using agent forwarding and it requires the SSH agent to understand the SSH_AGENTC_ADD_SMARTCARD_KEY command. It is unknown which SSH agents support this (OpenSSH does), the SSH library used by JGit has no API for it, and JGit doesn't do agent forwarding anyway. (To hop through servers to a git repository use ProxyJump instead.)

JGit by default uses the first token (the default slotListIndex zero). The Java KeyStore or Provider configuration does not seem to have any support for RFC7512 URIs to select the token. JGit provides a custom SSH configuration PKCS11SlotListIndex that can be set to the slot index of the token wanted. The value should be a non-negative integer. If not set or if negative, the first token (slot list index zero) is used. (Note that the value is the slot index, not the slot ID. Slot IDs are not necessarily stable.)

If you do set PKCS11SlotListIndex anywhere in your configuration file, then you should also set at the very top of the ~/.ssh/config file:

IgnoreUnknown PKCS11SlotListIndex

The IgnoreUnknown configuration tells OpenSSH to ignore configurations it doesn't know about. Without this option, OpenSSH will issue an error and exit if the config file contains PKCS11SlotListIndex. The IgnoreUnknown option is available in OpenSSH since version 6.3 from 2013-09-13. See the OpenSSH documentation for details.

If a token has multiple certificates and keys, a specific one can be selected by exporting the public key to a file and then using IdentitiesOnly and an IdentityFile configuration.

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.