NASA Insignia
Site Title

Console & SSH Logins for Macs with a PIV Smart Card

This page is a guide to help you login to your MacOS system using PIV smartcard badge.

PIV is Personal Identify Verification, and it includes the gold chip on the front of the badge. Please note that PIV is a prerequsite in order for you to login to your system.

If you do not have a smartcard reader, please obtain one from Akinola Bentham (6-6276) or Ozell Harris (6-9772).

Instructions for logging in to your Mac using your PIV Smart Card

  • Connect your card reader to your Mac, insert your card, and wait for it to be ready. (On most readers the light will stop flashing when it's ready.)
  • Wait a few (5-7?) seconds, and the prompt at the login screen should change from "Enter Password" to "PIN".
  • Enter your PIV card's PIN and hit Return.

Warning: if your machine is encrypted and you are restarting or cold-starting, you will need to unlock the disk with your password first and then follow the above procedure after the system presents you with a second login interface. This is because the initial FileVault mini-OS does not understand PIV cards (or much of anything else). If you get confused, you can tell you're in a FileVault dialog by the lack of a "Sleep" option at the bottom of the screen.

Using Secure Shell (SSH) with your PIV card on your Mac

Using your PIV card can actually be more convenient than using passwords, once you have everything set up (see below).

With your PIV card in the card reader (and the light flashing), do the following:

  • Type
    ssh-add -s /usr/lib/ssh-keychain.dylib
    After you hit return, enter your PIN at the prompt. You should only have to do this once per time you leave the PIV card in the reader.
  • Connect to another computer using
    ssh -A other_hostname
    The security banner should appear, with a slight delay (as your Public Key is retrieved and compared against your badge). It should then log you in without a password.
  • To do Secure Copy, do:
    scp -o "ForwardAgent=yes"
  • You can also edit (or create) ~/.ssh/config and add a section like this:
    
    	ForwardAgent yes
    
    This allows you to drop the '-A' or "-o 'ForwardAgent=yes' command line options.

You should be able to log in from your Mac to another Mac or to a Linux machine. You should also be able to do multiple hops (ssh hostA, then ssh hostB from hostA, etc).

NAMS Workflow for PIV Smart Card

This is necessary only if you intend to SSH into your Mac -- if you're just using the PIV to log in graphically, you don't need to bother.

  1. In a browser, go to NAMS (https://nams.nasa.gov).
  2. Log in with your Launchpad username and password.
  3. Click on "Your NAMS Requests."
  4. In the "NAMS" box, search for 251487 (which should then show "Public SSH Key Data Initialization Request)."

    You can ignore the desription (this is really for more than just Linux admins) and you can ignore the "MSFC" entry.

  5. Please change the "Request Sponsor," to Phillip Andrew Newman.
  6. Click on "Public SSH Key Data Initialization Request" link.
  7. Click the blue "Submit Request" button
  8. Please wait for the confirmation email before proceeding further.
  9. You only need to do this once per card, not once per machine.

Debugging

To see the status of your setup for ssh, please do:
ssh-add -l
(that's a lower-case 'L', not a one) to list your keys. If you don't see any keys listed , then add them as above:
ssh-add -s /usr/lib/ssh-keychain.dylib
If you get the error
Could not add card "/usr/lib/ssh-keychain.dylib": agent refused operation
then clear things out with:
ssh-add -e /usr/lib/ssh-keychain.dylib
then repeat:
ssh-add -s /usr/lib/ssh-keychain.dylib

Please note that you will need to repeat the ssh-add -s /usr/lib/ssh-keychain.dylib step after a reboot (the 'identities' do not survive across a restart).

Make sure your card reader is ready, which usually takes 5 seconds or so after your card is inserted. If not, please remove and reinsert the badge and/or unplug and replug the card reader itself. (Helpfully, some readers flash when they are ready, others flicker while reading the card and then are steadily lit when ready, and some just seem random! (sigh #1). Get to know your reader's working states.)

And be patient, you may have to wait up to 10 seconds for it to change states.

And you may have to do the remove badge/unplug card reader dance more than once. (sigh #2) (definition of insanity)

The unfortunate last-ditch solution to PIV card problems is to reboot the computer (sigh #3).

The truly last-ditch solution is to run the PIVManUndo process, which will remove all profiles -- including the PIV-enforcing ones -- from your machine. However, it's not for the faint of heart, requiring some command-line operations. It also will revert back to the original behavior about an hour after you connect the machine to any network, because when your computer phones home to Apple they'll tell it to go check in with the NASA Jamf server.

Shortcuts and aliases

So that you don't have to keep typing these paths, I have found that shell aliases can be useful.

I deliberately chose alias names that do not start with "ssh" to make it easier to still use 'ssh' easily as a command. And I use
"-s"="start" and "-e"="end" as mnemonics to keep the command flags straight. But do whatever makes sense to you!

for tcsh:

alias pivs '/usr/bin/ssh-add -s /usr/lib/ssh-keychain.dylib'
alias pive '/usr/bin/ssh-add -e /usr/lib/ssh-keychain.dylib'
alias pivl '/usr/bin/ssh-add -l'

for bash:

alias pivs='/usr/bin/ssh-add -s /usr/lib/ssh-keychain.dylib'
alias pive='/usr/bin/ssh-add -e /usr/lib/ssh-keychain.dylib'
alias pivl='/usr/bin/ssh-add -l'

David Friedlander
29 August 2018
Edited by Neal Sofge (FileVault)
04 December 2019