jgit/org.eclipse.jgit.ssh.apache/manual_tests.txt

46 lines
1.6 KiB
Plaintext
Raw Normal View History

ssh: PKCS#11 support Support PKCS#11 HSMs (like YubiKey PIV) for SSH authentication. Use the SunPKCS11 provider as described at [1]. This provider dynamically loads the library from the PKCS11Provider SSH configuration and creates a Java KeyStore with that provider. A Java CallbackHandler is needed to feed PIN prompts from the KeyStore into the JGit CredentialsProvider framework. Because the JGit CredentialsProvider may be specific to a SSH session but the PKCS11Provider may be used by several sessions, the CallbackHandler needs to be configurable per session. PIN prompts respect the NumberOfPasswordPrompts SSH configuration. As long as the library asks only for a PIN, we use the KeyPasswordProvider to prompt for it. This gives automatic integration in Eclipse with the Eclipse secure storage, so a user has even the option to store the PIN there. (Eclipse will then ask for the secure storage master password on first access, so the usefulness of this is debatable.) By default the provider uses the first PKCS#11 token (slot list index zero). This can be overridden by a non-standard PKCS11SlotListIndex ssh configuration entry. (For OpenSSH interoperability, also set "IgnoreUnknown PKCS11SlotListIndex" in the SSH config file then.) Once loaded, the provider and its shared library and the keys contained remain available until the application exits. Manually tested using SoftHSM. See file manual_tests.txt. Kudos to Christopher Lamb for additional manual testing with a real YubiKey, also on Windows.[2] [1] https://docs.oracle.com/en/java/javase/11/security/pkcs11-reference-guide1.html [2] https://www.eclipse.org/forums/index.php/t/1113295/ Change-Id: I544c97e1e24d05e28a9f0e803fd4b9151a76ed11 Signed-off-by: Thomas Wolf <twolf@apache.org>
2023-07-09 21:06:37 +03:00
Testing PKCS11 support
----------------------
# Install SoftHSM and OpenSC
I got SoftHSM via MacPorts, and OpenSC from https://github.com/OpenSC/OpenSC#downloads
You need both; softhsm2-util cannot import certificates.
# Initialize SoftHSM
$ softhsm2-util --init-token --slot 0 --label "TestToken" --pin 1234 --so-pin 4567
The token has been initialized and is reassigned to slot 2006661923
# Create a new RSA key and certificate
$ openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -subj "/CN=MyCertTEST" -nodes
# Import the RSA key pair into the SoftHSM token
$ softhsm2-util --import key.pem --slot 2006661923 --label "testkey" --id 1212 --pin 1234
# Convert the certificate to DER and import it into SoftHSM token
$ openssl x509 -in cert.pem -out cert.der -outform DER
$ pkcs11-tool --module /opt/local/lib/softhsm/libsofthsm2.so -l --id 1212 --label "testcert" -y cert -w cert.der --pin 1234
# Export the RSA public key convert to PEM, and show in SSH format
# (I'm sure this could be done simpler from the original key.pem, but what the heck.)
pkcs11-tool --module /opt/local/lib/softhsm/libsofthsm2.so --slot 2006661923 --read-object --type pubkey --id 1212 -o key.der
openssl rsa -pubin -inform DER -in key.der -outform PEM -out key.pub.pem
ssh-keygen -f key.pub.pem -m pkcs8 -i
# Install that public key at Gerrit (or your git server of choice)
# Have an ~/.ssh/config with a host entry for your git server using the SoftHSM library as PKCS11 provider:
Host gitserver
Hostname git.eclipse.org
Port 29418
User ...
PKCS11Provider /opt/local/lib/softhsm/libsofthsm2.so
# Fetch from your git server! When asked for the PIN, enter 1234.