III. YubiKey Mac SSH Client Configuration

Owned by Tony Lam
Last updated: Nov 11, 2024

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.

This was tested on macOS Big Sur 11.6.5, ymmv.

Prerequisites

Setup

Install Software

Once a Smartcard has been setup and configured:

OpenSC (Available via self-service for managed machines)

  1. Install OpenSC package.

    • Obtain the dmg image from this url: OpenSC
      • OpenSC-0.22.0.dmg (as of 3/16/2022)
    • Open the downloaded dmg file.
    • Open the OpenSC *.pkg file to begin the install process.
      • If you receive the following popup stating the pkg can't be opened 

      • Right-click on the installer and select Open (it might be command right-click if one or the other works please update this doc)
      • Another popup will show, but you will be able to click Open to continue
    • Defaults of the install are perfectly a-ok

SSH-Askpass

Note 1

This example uses an osascript from github.

http://github.com/theseal/ssh-askpass

  1. Navigate to a folder where you want to keep the ssh-askpass repository. For example, your home directory:

    $ cd ~

  2. Using git pull down the repository locally

    $ git clone https://github.com/theseal/ssh-askpass.git ssh-askpass

    Note 2

    This will probably pop up requesting to install command line developer tools. Go ahead and install it.

  3. Set up environment to work with ask-pass:

     Mojave users here

    Current version doesn't appear to work. You will need to revert to an older version of the applescript.

    cd ssh-askpass
git checkout -b v1.2.2 v1.2.2
<RUN THROUGH THE ORIGINAL STEPS BELOW>

Reverting the git back to master:
git checkout master
git branch -d v1.2.2
    $ cd ssh-askpass
$ sudo cp ssh-askpass /usr/local/bin/
$ cp ssh-askpass.plist ~/Library/LaunchAgents/
$ launchctl load -w ~/Library/LaunchAgents/ssh-askpass.plist

    Nothing will happen here, continue onward to Usage

    It seems that ssh-add requires that the DISPLAY environment variable be set in order to execute ssh-askpass.  There are a couple of ways to accomplish this, the easiest is to just install xquartz.  If you want you can also add it to your profile.

Usage

OpenSC + ssh-askpass

  1. After the OpenSC software is installed, open Terminal and validate the opensc-pkcs11.so exists within the /usr/local/lib directory.

    % ls -l /usr/local/lib | grep opensc
total 19824
-rwxr-xr-x  1 root  admin  5072000 Mar 16 17:55 onepin-opensc-pkcs11.so
-rwxr-xr-x  1 root  admin  5071984 Mar 16 17:55 opensc-pkcs11.so

    Note 3

     If the files don't show up

    If the libraries above don't exist, You will need to ensure that lib directory exists and then run the OpenSC installer again.

    sudo mkdir /usr/local/lib

    Run the OpenSC installer again once the directory is created.

  2. Using a Terminal window, 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/local/lib/opensc-pkcs11.so 
Enter passphrase for PKCS#11:

  3. When successful, you will see the following message and will be able to verify with the following command(s).

    Card added: /usr/local/lib/opensc-pkcs11.so
% ssh-add -L
ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC1tm0mikWaHIfhb055vy3cYIl9azAqWVKjoAAouBsU61FgJ+edt7RinkY6GTPZf07pATlLzYY3+FOQIh5MRkAhmMp2fi0/YZgFmMBKkGy84OFLvmczp+lb8b/LPIu2qLVaCumoksdDNT8z29e99PZMh0XhXzSh+cIWujGn4gEFFjlJn03OWxs7IRBaBz32uLCfV6wQeZtPWQiodvhNo39GK/XXrPIbiRbC2NEfCUxSo+493TKIISORLYAibLdlKPVIHHU9+1ZknbOeFXpMADi0z4LYhrRN9BRfdFfheInMQlVk2hqUD9SMWWgMkIiiK/y1IsBVqjkfiDe8AVbmDDvd /usr/local/lib/opensc-pkcs11.so

---

% ssh-add -l
2048 SHA256:MSOJ3pXOzF1eLmAwvII7VSNzCJNGq2viE4kwFyUQQHM /usr/local/lib/opensc-pkcs11.so (RSA)

    Note 4

    From OpenSSH 8.1p1 manpages for 'ssh-add':
    -L      Lists public key parameters of all identities currently represented by the agent.
    -l      Lists fingerprints of all identities currently represented by the agent.

  4. 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.

    Note 5

     Click here to expand...

    Initial connection will see the following popup:


    Click OK to allow.


    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 6

    From OpenSSH 8.1p1 manpages for 'ssh':

    -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

  5. To remove the key from ssh-agent, you can run the ssh-add command with the -e switch.

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

Misc