ProxyJump allows a user to confidentially tunnel an SSH session through a central host with end-to-end encryption. The steps below cover setting up and using ProxyJump with YubiKeys. This guide assumes a YubiKey that has its PIV application pre-provisioned with one or more private keys and corresponding certificates, etc.
Step 1 - Install YKCS11
Windows
To use Windows' native SSH client with the PIV smart card function of the YubiKey, you will need to download and install Yubico's YKCS11 library, which comes bundled with the Yubico PIV Tool.
To obtain a copy of YKCS11, head over to https://developers.yubico.com/yubico-piv-tool/Releases/, download the latest release for your system architecture, and install it. For example, if you're running 64-bit Windows, you should download the file ending with -win64.msi (under the latest version heading). For 32-bit Windows, download the one ending in -win32.msi instead.
Next, verify that your OpenSSH installation is at least 8.1p1 by running ssh -V in PowerShell. Your output should resemble OpenSSH_for_Windows_8.1p1, LibreSSL 3.0.2.
If an earlier version is reported, you'll need to update your OpenSSH installation.
Once you've verified you meet the minimum requirements and have installed YKCS11, open PowerShell and run the following.
New-Item -Path $env:USERPROFILE\.ssh\ -Name "config" -ItemType "file" -Value 'PKCS11Provider "C:\Program Files\Yubico\Yubico PIV Tool\bin\libykcs11.dll"'
This configures Windows' SSH client to use YKCS11 to access the YubiKey. Note, if you installed the 32-bit PIV Tool on 64-bit Windows, your path will differ slightly (it will begin with C:\Program Files (x86) instead of C:\Program Files).
You can verify that this command succeeded by running:
type $env:USERPROFILE\.ssh\config
If everything is in order, this command's output should be PKCS11Provider "C:\Program Files\Yubico\Yubico PIV Tool\bin\libykcs11.dll". Note, if you installed the 32-bit PIV Tool on 64-bit Windows, your path will differ slightly (it will begin with C:\Program Files (x86) instead of C:\Program Files).
MacOS
YKCS11 can be installed via our Yubico PIV tool application: https://developers.yubico.com/yubico-piv-tool/Releases/.
Once installed, the YKCS11 library will be located at /usr/local/lib/libykcs11.dylib.
Ubuntu
Install YKCS11 from Ubuntu's preconfigured repositories by running:
sudo apt update && sudo apt install ykcs11
After installing YKCS11, the library will be located at /usr/local/lib/libykcs11.
CentOS / Rocky Linux
At this time, the only way to obtain YKCS11 on CentOS/Rocky Linux is to compile the Yubico PIV Tool from source. Source code for the Yubico PIV Tool can be downloaded from https://developers.yubico.com/yubico-piv-tool/Releases/.
Step 2 - Export public key
Export the public key from the YubiKey using a command like one of the following (be sure to change the path accordingly), then add it to the authorized_keys file on the target systems.
Windows
ssh-keygen -D /path/to/libykcs11.dll -e
macOS
ssh-keygen -D /path/to/libykcs11.dylib -e
Linux
ssh-keygen -D /path/to/libykcs11.so -e
NOTE: These commands export all public keys stored in the YubiKey PIV app. The slot order should remain the same, thereby facilitating identification of the public key associated with your targeted private key.
Step 3 - Set YKCS11 as default PKCS11 provider
Add a line like one of the following to the file ~/.ssh/config. As with step 2, be sure to adjust the path to YKCS11 accordingly. This will set the default PKCS11 provider to YKCS11. For Windows, this was already done as part of step 1.
MacOS
PKCS11Provider /path/to/libykcs11.dylib
Linux
PKCS11Provider /path/to/libykcs11.so
Step 4 - Login via ProxyJump
Simple method:
Run a command in the following form, replacing user, proxy.host, etc. with their correct values.
ssh -J user@proxy.host user@dest.host
You should be presented with a prompt for the YubiKey's PIV PIN resembling the following. You will be requested to enter this PIN once per host.
Enter PIN for 'YubiKey PIV #12345678':
Advanced configuration
Using the below example as a guide, configure your ~/.ssh/config file to define the hosts you wish to ssh to/proxy through, as well as the usernames you would like to use to authenticate to each host. As shown in the example, the proxy host's config/definition block should include the keyword ProxyJump. See https://man.openbsd.org/ssh_config#ProxyJump for additional details.
PKCS11Provider /path/to/libykcs11
Host A
Hostname <IP or Hostname>
User <ssh user>
Port 22
Host B
Hostname <IP or Hostname>
ProxyJump A
User <ssh user>
Port 22
With this configuration completed, simply typing the following command will allow you to login to host B using host A as a proxy.
ssh B
After running ssh B, you should be presented with a prompt for the YubiKey's PIV PIN resembling the following. You will be requested to enter this PIN once per host.
Enter PIN for 'YubiKey PIV #12345678':