1. Home
  2. PIV
  3. Guides
  4. SSH with PIV and PKCS11

    Using PIV for SSH through PKCS #11

    This is a step-by-step guide on setting up a YubiKey with PIV to work for public-key authentication with OpenSSH through PKCS #11. These instructions apply primarily to macOS and Linux systems.

    Note
    		 There are multiple ways to use YubiKeys for SSH. See SSH for options.

    Prerequisites

    • a YubiKey with the PIV application loaded

    • the yubico-piv-tool software (download from yubico-piv-tool releases)

    • OpenSSH

    • For macOS, iOS 10.13 and later are supported

    OpenSC is no longer required, since we now have a functional PKCS #11 module, namely ykcs11.

    Note
    		 RSA 4096-bit and RSA 3072-bit keys require YubiKey firmware version 5.7 or later.
    Note
    		 We strongly recommend changing the management key; keeping the default management key is explicitly discouraged. The examples given in the following steps assume that you have not yet changed the management key. If you have changed the management key, add --key to the yubico-piv-tool -a import-certificate command below.

    Procedure

    Step 1: Import or generate a key in slot 9a (any slot should suffice):

    Either import the key (PEM format):

    yubico-piv-tool -s 9a -a import-key -i key.pem
    Note
    		 If an external key has been imported and a certificate already exists, skip step 2.

    or generate the key:

    yubico-piv-tool -s 9a -a generate -o public.pem

    Step 2: Create a self-signed certificate for that key. The only use for the X.509 certificate is to satisfy PIV/PKCS #11 lib. It needs to be able to extract the public-key from the smartcard, and to do that through the X.509 certificate.

    yubico-piv-tool -a verify-pin -a selfsign-certificate -s 9a -S "/CN=SSH key/" -i public.pem -o cert.pem
    Note
    		 This command will prompt for the PIV PIN. The default PIV PIN is 123456. You should change the default PIN before generating keys with yubico-piv-tool -a change-pin.

    Step 3: Load the certificate:

    yubico-piv-tool -a import-certificate -s 9a -i cert.pem

    Step 4: Find out where ykcs11 has been installed. For a Debian-based system, the ykcs11 module ends up in /usr/local/lib/libykcs11. On MacOS, it is in /usr/local/lib/libykcs11.dylib.

    Step 5: Export the public key in correct format for SSH and then add it to authorized_keys on the target system.

    ssh-keygen -D XXX/libykcs11.so -e
    Note
    		 This command will export all keys stored on the YubiKey. The slot order should remain the same, thereby facilitating identification of the public key associated with your targeted private key.

    Step 6: Authenticate to the target system using the new key:

    ssh -I XXX/libykcs11.so user@remote.example.com

    Step 7: (Optional) This can also be set up to work with ssh-agent:

    ssh-add -s XXX/libykcs11.so

    Confirm that the ssh-agent finds the correct key and gets the public key in the correct format by running:

    ssh-add -L