🟣PIV-PKCS
Instructions for configuring SSH utilizing PKCS protocol.
Last updated
Instructions for configuring SSH utilizing PKCS protocol.
Last updated
For this tutorial; we're going to create a PIV certificate/keys and import them into slot 9A of your Yubikey.
Before continuing, you need to follow the instructions provided in the and generate the certs and keys you will use for connecting. Once you have finished, return to this guide and proceed to the next step.
To authenticate with your SSH server using your PIV certificate; you must use the application PuTTY-CAC. This program is different from PuTTY; and provides you with extra features you will need in order to do this.
You can download PuTTY-CAC here.
Once PuTTY-CAC is installed and launched, you can fill out the information for the server you wish to connect to:
This includes your hostname and port.
You can then enter a name under Saved Sessions and then click Save. This will store your server in your favorites so that you can access it more quickly later.
If you make changes to the configuration, remember to click Save.
Next, navigate to Connection -> SSH -> Certificate:
There are several options that you can select from, minaly Set CAPI and Set PKCS. For this tutorial; we're going to select PKCS. If you use to utilize the CAPI protocol, you can follow that guide here.
The dialog above is asking you to select the PKCS module file that will be used to load your Yubikey's PIV certificates.
You should navigate and select the file:
C:\Program Files\Yubico\Yubico PIV Tool\bin\libykcs11.dll
If you do not have the above folders, you will need to download the Yubikey Manager, and the Yubikey PIV Tool from their official website.
Once you select the correct .DLL file, another dialog should appear and list the PIV certificates available from your Yubikey:
Select the certificate you created earlier and press OK.
If you wish to save this certificate as part of your Favorites, go back and press Save again on the Saved Sessions section.
The next step to get SSH authentication working, giving your remote server your certificate key.
In PuTTY-CAC, navigate to Connection -> SSH -> Certificate
Toward the bottom of the list of protocol buttons, you should see a button labeled Copy to Clipboard.
This should copy your public key to your clipboard which you will need to add to your remote server's authorized_keys file, usually located in:
/home/username/.ssh/authorized_keys
If you're attempting to apply your public key to your root user, you will need to modify:
/root/.ssh/authorized_keys
It is highly recommended that you not utilize your root account. Create a new user to authenticate with, and disable the root account on your server.
Inside the authorized_keys file, paste the public key that was copied to your clipboard from PuTTY-CAC and then save the file.
If you have multiple certificates you wish to use to connect, you can paste each public key on a new line in the authorized_keys file.
Ensure your .ssh folder and authorized_keys files have the correct permissions.
.ssh/
700
.ssh/authorized_keys
644
Also check and make sure the folder and files are owned by the user that the account is associated to. Execute chown if the .ssh folder and files are owned by root and not the account the folders are listed under. Failure to properly set the permissions on these files / folder will result in authentication not working.
PuTTY-CAC will open the SSH terminal and ask you to supply your username:
Once your username is entered, the terminal will show a few lines of text.
And a PIN dialog will appear which asks you to enter your Yubikey PIV PIN:
Once your PIN is entered, take a quick look at the circle in the middle of your Yubikey. If you imported your PIV certificate with a specified TOUCH POLICY; your Yubikey will ask you to press the button in the middle before authentication is completed. If you do not press the button within 30 seconds, the connection will be terminated.
The terminal will then print a few more lines once you've connected and you'll be ready to go:
Once you have successfully connected to your SSH server with your Yubikey, you may want to disable the ability to sign into your user with a password. This ensures only authentication with the Yubikey is allowed.
To do this, locate and open your sshd_config file, usually located in:
/etc/ssh/sshd_config
Once the file is open, find the line which includes:
Modify the line's value to disable password authentication:
Once the change has been made, you will need to restart SSH on your server with any of the following commands:
The command syntax depends on which distro of Linux you are running.
This completes this section of the guide. If you wish to utilize the CAPI protocol for connecting, you may view the PIV-CAPI SSH Guide here.
One of the biggest pains of getting SSH + PuTTY-CAC to connect successfully with a Yubikey is the poorly worded dialog box, and using the incorrect module.
When prompted to enter your "password", it wants you to enter your Yubikey PIV PIN, not your PIV certificate passphrase / password. The CAPI method is much more clear and uses the proper PIN dialog box, whereas PKCS doesn't.
The second issue is using the correct .dll module.
You should NOT be using the OpenSC .dll located in C:\Program Files\OpenSC Project\OpenSC\pkcs11\opensc-pkcs11.dll, but instead, point the browse dialog to where you have libykcs11.dll on your computer. This is typically in the folder:
C:\Program Files\Yubico\Yubico PIV Tool\bin\libykcs11.dll
These steps should ensure that you successfully connect to your server via SSH.
Personally, I'm more of a fan of CAPI, but whichever you prefer.
Because PuTTY-CAC uses OpenSC as the bridge between PuTTY and your server, you cannot run multiple programs that rely on OpenSC at the same time; otherwise you will get errors, or cannot see your PIV certificates.
Such an example would be running PuTTY and Filezila at the same time, and having both connections authenticate using your Yubikey.
Set PKCS CertIf PuTTY becomes unresponsive when you click the Set PKCS Cert button, this is usually because you clicked the button too quick after inserting your Yubikey. Once you insert the Yubikey, wait about 10-15 seconds before clicking. PuTTY doesn't like when you try to speed-run the program.
This error appears when your attempt to authenticate using your Yubikey has failed, and your SSH server has no other way to connect. The most common reason is if you edit your sshd_config file and disable password authorization.
To correct this issue, follow through the guide steps again, and make sure you're using your Yubikey PIV PIN to authenticate, and not a certificate password.
If you continue to get the error and have no idea why it's appearing, you can re-enable PasswordAuthentication.
Next, select , which should make a dialog box appear.
Once you have added your public key to your server and selected the correct certificate, you can now click the button.
