# JGit

## Features

### SSH Connections support PKCS#11 Hardware Security Modules

The SSH transport `org.eclipse.jgit.ssh.apache` of JGit 6.7.0 supports using PKCS#11 Hardware Security Modules (HSM) for public-key authentication. It uses Java's built-in mechanisms to access PKCS#11-compliant HSMs via the `SunPKCS11` security provider.

This can be configured in the SSH configuration file `~/.ssh/config` as follows:

     Host git.acme.com
     Hostname ...
     User ...
     PKCS11Provider /absolute/path/to/pkcs11/shared/library

The "PKCS#11 shared library" is typically provided by the vendor of the HSM; it provides the standard PKCS#11 API to the device. If the path contains blanks, quote it with double quotes.

HSMs may have multiple "slots" containing different tokens. JGit by default uses keys from the first slot/token. To select a different slot, use a config like

     # At the very top of the file: tell OpenSSH to ignore this option, which it doesn't know
     IgnoreUnknown PKCS11SlotListIndex
     ...
     Host git.acme.com
     Hostname ...
     User ...
     PKCS11Provider /absolute/path/to/pkcs11/shared/library
     PKCS11SlotListIndex <slot number>

Note that this is the slot index, not the slot ID. The index is just a number, the first slot has index 0, the next 1, and so on.

Some slots may contain multiple certificates or keys. JGit just tries all keys from a slot in the order they are delivered by the `SunPKCS11` provider. To specify that a particular key should be used, export the public key to a file, say `~/.ssh/my_hsm_key.pub`, in SSH format.

    (Please consult the documentation provided by the vendor of the HSM on how to export a public key. Once it exists as a PEM file, it can be converted to SSH format using `ssh-keygen -f my_hsm_key.pem -m pkcs8 -i > ~/.ssh/my_hsm_key.pub`.)

Then use `IdentityFile`, plus `IdentitiesOnly` to specify that only the keys listed via `IdentityFile` shall be used:

     Host git.acme.com
     Hostname ...
     User ...
     PKCS11Provider /absolute/path/to/pkcs11/shared/library
     IdentityFile ~/.ssh/my_hsm_key
     IdentitiesOnly yes

Note that there is no "`.pub`" file extension for the `IdentityFile`, and this file without the `.pub` suffix need not (and usually will not) exist. But the corresponding `~/.ssh/my_hsm_key.pub` should exist!

### Other Features

- JGit has learned to read the git config file `$XDG_CONFIG_HOME/git/config`, if it exists, in addition to the global git config file in the user's home directory.

## Other Changes

The complete list of new features and bug fixes is available in the release notes.