# PIV-PKCS

## <mark style="color:red;">❊ Creating PIV Keys & Certificate</mark>

For this tutorial; we're going to create a PIV certificate/keys and import them into slot <mark style="color:red;">**`9A`**</mark> of your Yubikey.

Before continuing, you need to follow the instructions provided in the [**PIV Slot 9A guide**](/yubikey5/piv-1/slots/9a/openssl.md) 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.

## <mark style="color:red;">❊ PuTTY-CAC</mark>

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**](https://github.com/NoMoreFood/putty-cac/releases/).

Once PuTTY-CAC is installed and launched, you can fill out the information for the server you wish to connect to:

<figure><img src="/files/jykep1679VPdFUPJ6yO1" alt=""><figcaption></figcaption></figure>

This includes your hostname and port.

You can then enter a name under <mark style="color:red;">**Saved Sessions**</mark> and then click <mark style="color:red;">**Save**</mark>. 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 <mark style="color:red;">**Connection**</mark> -> <mark style="color:red;">**SSH**</mark> -> <mark style="color:red;">**Certificate**</mark>:

<figure><img src="/files/rsoLYyrMU2E7A6H5X7Nw" alt=""><figcaption></figcaption></figure>

There are several options that you can select from, minaly Set <mark style="color:yellow;">**`CAPI`**</mark> and Set <mark style="color:yellow;">**`PKCS`**</mark>. For this tutorial; we're going to select <mark style="color:red;">**`PKCS`**</mark>. If you use to utilize the CAPI protocol, [**you can follow that guide here.**](/yubikey5/tutorials/ssh-+-putty-cac/piv-capi.md)

Next, select ![](/files/IEQ593VIpQZQ1Nr8X2mv), which should make a dialog box appear.

<figure><img src="/files/d641FB5EnKXLF0btYWwB" alt=""><figcaption></figcaption></figure>

The dialog above is asking you to select the PKCS module file that will be used to load your Yubikey's PIV certificates.&#x20;

You should navigate and select the file:

<mark style="color:red;">**`C:\Program Files\Yubico\Yubico PIV Tool\bin\libykcs11.dll`**</mark>

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:

<figure><img src="/files/GU5f1fIvKjH87Asi5uZD" alt=""><figcaption></figcaption></figure>

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.

## <mark style="color:red;">❊ Install Public Key</mark>

The next step to get SSH authentication working, giving your remote server your certificate key.

In PuTTY-CAC, navigate to <mark style="color:red;">**Connection**</mark> -> <mark style="color:red;">**SSH**</mark> -> <mark style="color:red;">**Certificate**</mark>

Toward the bottom of the list of protocol buttons, you should see a button labeled <mark style="color:red;">**`Copy to Clipboard`**</mark>.

<figure><img src="/files/JscerKh2P699CJILjdm2" alt=""><figcaption></figcaption></figure>

This should copy your public key to your clipboard which you will need to add to your remote server's <mark style="color:red;">**`authorized_keys`**</mark> file, usually located in:

<mark style="color:red;">**`/home/username/.ssh/authorized_keys`**</mark>

If you're attempting to apply your public key to your root user, you will need to modify:

<mark style="color:red;">**`/root/.ssh/authorized_keys`**</mark>

{% hint style="info" %}
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.
{% endhint %}

Inside the <mark style="color:red;">**`authorized_keys`**</mark> 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.

<table><thead><tr><th width="290">File</th><th>Permission</th></tr></thead><tbody><tr><td><mark style="color:red;"><strong><code>.ssh/</code></strong></mark></td><td><code>700</code></td></tr><tr><td><mark style="color:red;"><strong><code>.ssh/authorized_keys</code></strong></mark></td><td><code>644</code></td></tr></tbody></table>

Also check and make sure the folder and files are owned by the user that the account is associated to. Execute <mark style="color:red;">**`chown`**</mark> 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.

## <mark style="color:red;">❊ Connection</mark>

Once you have added your public key to your server and selected the correct certificate, you can now click the ![](/files/z3tXG2JSONDTIj97TPig) button.

PuTTY-CAC will open the SSH terminal and ask you to supply your username:

<figure><img src="/files/lqkOSXwfJm4NBgfGtxjj" alt=""><figcaption></figcaption></figure>

Once your username is entered, the terminal will show a few lines of text.

```
login as: aetherinox
Pre-authentication banner message from server:
| ---------------------------------------------------------
| Authorized Access Only
| ---------------------------------------------------------
End of banner message from server
Authenticating with public key "PKCS:4195a02b5e969e11e2ab8eac536f24aac589
```

And a PIN dialog will appear which asks you to enter your Yubikey PIV PIN:

<figure><img src="/files/DvLH7NqeM8cyQAl7O708" alt=""><figcaption></figcaption></figure>

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:

```
Welcome to Zorin OS 16.2 (GNU/Linux 5.15.0-58-generic x86_64)
Last login: Sun Feb 12 18:06:39 2023

username@home:~$
```

## <mark style="color:red;">❊ Passwordless Authentication</mark>

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:

<mark style="color:red;">**`/etc/ssh/sshd_config`**</mark>

Once the file is open, find the line which includes:

```bash
PasswordAuthentication yes
```

Modify the line's value to disable password authentication:

```bash
# To disable tunneled clear text passwords, change to no here!
# Disable password authentication by default (except for LAN IP ranges listed later)

PasswordAuthentication no
```

Once the change has been made, you will need to restart SSH on your server with any of the following commands:

```bash
/etc/init.d/sshd restart
service sshd restart
sudo systemctl restart sshd
service ssh restart
```

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**](/yubikey5/tutorials/ssh-+-putty-cac/piv-capi.md).

## <mark style="color:red;">❊ Notes</mark>

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.

<figure><img src="/files/VQr7eFLv3mt8MIKrCH0j" alt=""><figcaption></figcaption></figure>

The second issue is using the correct .dll module.

You should <mark style="color:red;">**NOT**</mark> be using the OpenSC .dll located in <mark style="color:red;">**`C:\Program Files\OpenSC Project\OpenSC\pkcs11\opensc-pkcs11.dll`**</mark>, but instead, point the browse dialog to where you have <mark style="color:blue;">**`libykcs11.dll`**</mark> on your computer. This is typically in the folder:

<mark style="color:red;">**`C:\Program Files\Yubico\Yubico PIV Tool\bin\libykcs11.dll`**</mark>

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.&#x20;

{% hint style="warning" %}
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.
{% endhint %}

### <mark style="color:blue;">Common Errors / Issues</mark>

### <mark style="color:red;">**Interface Freezing When selecting**</mark><mark style="color:red;">**&#x20;**</mark><mark style="color:red;">**`Set PKCS Cert`**</mark>

<figure><img src="/files/Y6DZUUZUuXvr1ns6rN4r" alt=""><figcaption></figcaption></figure>

If PuTTY becomes unresponsive when you click the <mark style="color:red;">**`Set PKCS Cert`**</mark> 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.

### <mark style="color:red;">**Error: No supported authentication methods available.**</mark>

<figure><img src="/files/KvbExvPBrBRENSfdQFKz" alt=""><figcaption></figcaption></figure>

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.

```bash
# To disable tunneled clear text passwords, change to no here!
# Disable password authentication by default (except for LAN IP ranges listed later)

PasswordAuthentication no
```

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 <mark style="color:red;">**`PasswordAuthentication`**</mark>.

```bash
PasswordAuthentication yes
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://yubico.gitbook.io/yubikey5/tutorials/ssh-+-putty-cac/piv-pkcs.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.