1 files changed, 160 insertions, 0 deletions
diff --git a/org.eclipse.jgit.ssh.apache/README.md b/org.eclipse.jgit.ssh.apache/README.md
new file mode 100644
index 0000000000..b2911c688c
--- /dev/null
+++ b/org.eclipse.jgit.ssh.apache/README.md
@@ -0,0 +1,160 @@
+# JGit SSH support via Apache MINA sshd
+
+This bundle provides an implementation of git transport over SSH implemented via
+[Apache MINA sshd](https://mina.apache.org/sshd-project/).
+
+## 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:
+
+```java
+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](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 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](https://docs.oracle.com/en/java/javase/11/security/pkcs11-reference-guide1.html)
+does not seem to have any support for [RFC7512](https://www.rfc-editor.org/rfc/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](https://man.openbsd.org/ssh_config.5#IgnoreUnknown)
+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.