III. YubiKey Linux SSH Client Configuration

Overview

This guide is intended to provide bare minimum steps for using a certificate on YubiKey with ssh-agent and forwarding it via ssh to use on remote host.

Depending on the Linux distribution used, some steps may need to be modified/added/removed.

Prerequisites

Setup

Install Software

Once a Smartcard has been setup and configured:

OpenSC

  1. Install OpenSC package for your distribution

     Fedora example
    # dnf install opensc
     Ubuntu example
    # apt install opensc

SSH-Askpass

Note 1

This example uses openssh-askpass/ssh-askpass-gnome. Another popular option is x11-ssh-askpass.

This also infers the use of a GUI.

  1. Install the ssh-askpass package for your distribution

     Fedora/RHEL
    # dnf install openssh-askpass
     Ubuntu/Debian
    # apt install ssh-askpass-gnome
  2. Locate where the ssh-askpass binary is installed.

     Fedora/RHEL
    /usr/libexec/openssh/ssh-askpass
     Ubuntu
    /usr/lib/openssh/gnome-ssh-askpass
  3. Ensure your environment variable for SSH_ASKPASS and SSH_ASKPASS_REQUIRE is set correctly. You will want this to be configured on startup.

     Bash on Fedora/RHEL
    export SSH_ASKPASS=/usr/libexec/openssh/ssh-askpass
    export SSH_ASKPASS_REQUIRE=force
     Bash on Ubuntu
    export SSH_ASKPASS=/usr/lib/openssh/gnome-ssh-askpass
    export SSH_ASKPASS_REQUIRE=force

Usage

OpenSC + ssh-askpass

  1. After the OpenSC software is installed, you'll need to find the full path to the library file, opensc-pkcs11.so.
    This will usually be located in one of the following directories:

    /usr/local/lib
    /usr/local/lib64
    /usr/lib
    /usr/lib64
  2. Most OS's will already have some form of ssh-agent running. If not, start ssh-agent.
  3. Add your certificate to ssh-agent, by running the following command. It will prompt you for your PIN.

    The following command will need to be run on each reboot as a reboot resets the ssh-agent

    $ ssh-add -c -s /usr/lib64/opensc-pkcs11.so 
    Enter passphrase for PKCS#11: 
  4. When successful, you will see the following message and will be able to verify with the following command(s).

    Card added: /usr/lib64/opensc-pkcs11.so
    $ ssh-add -L
    ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC1tm0mikWaHIfhb055vy3cYIl9azAqWVKjoAAouBsU61FgJ+edt7RinkY6GTPZf07pATlLzYY3+FOQIh5MRkAhmMp2fi0/YZgFmMBKkGy84OFLvmczp+lb8b/LPIu2qLVaCumoksdDNT8z29e99PZMh0XhXzSh+cIWujGn4gEFFjlJn03OWxs7IRBaBz32uLCfV6wQeZtPWQiodvhNo39GK/XXrPIbiRbC2NEfCUxSo+493TKIISORLYAibLdlKPVIHHU9+1ZknbOeFXpMADi0z4LYhrRN9BRfdFfheInMQlVk2hqUD9SMWWgMkIiiK/y1IsBVqjkfiDe8AVbmDDvd /usr/lib64/opensc-pkcs11.so
    
    ---
    
    $ ssh-add -l
    2048 SHA256:MSOJ3pXOzF1eLmAwvII7VSNzCJNGq2viE4kwFyUQQHM /usr/lib64/opensc-pkcs11.so (RSA)

    Note 2

    From OpenSSH 8.0p1 manpages:
    -L      Lists public key parameters of all identities currently represented by the agent.
    -l      Lists fingerprints of all identities currently represented by the agent.

  5. Now to use the certificate, you will need to forward the agent connection to the remote host. This is done with the -A switch for ssh command.
    You will see the following prompt when you ssh to or sudo on a remote machine.

     x11-ssh-askpass


    Once logged in, you should be able to run the ssh-add command to verify the remote host is able to see your certificate.

    $ ssh -A mgmt.rit.edu
    ---
    (mgmt)$ ssh-add -l
    2048 SHA256:MSOJ3pXOzF1eLmAwvII7VSNzCJNGq2viE4kwFyUQQHM /usr/lib64/opensc-pkcs11.so (RSA)

    Note 3

    From OpenSSH 8.0p1 manpages:

    -A      Enables forwarding of the authentication agent connection.  This can also be specified on a per-host basis in a configuration file.

    Agent forwarding should be enabled with caution.  Users with the ability to bypass file permissions on the remote host (for the agent's UNIX-domain socket) can access the local agent through the forwarded connection.  An attacker cannot obtain key material from the agent, however they can perform operations on the keys that enable them to authenticate using the identities loaded into the agent.


    OR
    Another option is to modify your local ssh config in ~/.ssh/config:

    Host *
      ForwardAgent yes
  6. To remove the key from ssh-agent, you can run the ssh-add command with the -e switch.

    % ssh-add -e /usr/lib64/opensc-pkcs11.so 
    Card removed: /usr/lib64/opensc-pkcs11.so