Skip to main content

Notice: This Wiki is now read only and edits are no longer possible. Please see: for the plan.

Jump to: navigation, search

JGit/New and Noteworthy/6.7



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:

 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
 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/, 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/

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

 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/ 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.


The following 15 developers worked on this release:

Anna Papitto, Antoine Musso, David Ostrovsky, Haamed Gheibi, Han-Wen Nienhuys, Ivan Frade, Jonathan Tan, Jörg Kubitz, Luca Milanesio, Martin Fick, Matthias Sohn, Nitzan Gur-Furman, Qin Shulei, Ronald Bhuleskar, Thomas Wolf

Back to the top