enable PIV/CAC for SSH to a Unix-like system

[GSAllewell]

How To – PuTTY-CAC – Install, set up, and log on

Background

Most Unix-like systems are configured to use the SSH protocol for remote access, but most SSH client applications do not support PIV as required by Federal policy. PuTTY-CAC, a fork of the Open Source PuTTY SSH client, resolves this issue. Van Dyke Secure CRT, a commercial product, also supports PIV SSH login for multiple platforms, including Windows and Mac.

Installing PuTTY-CAC

1. If you have a forge.mil account, download the latest PuTTY-CAC package from forge.mil. If you do not have access to forge.mil, you can also download it at https://risacher.org/putty-cac. Source code is available at https://github.com/risacher/putty-cac
2. There is no installer available for the binaries, so you must either:
   • Place the executable files in directly in a directory that you have execute rights over.
   • Build an installation package to install the executables in the location you choose. This will enable the PuTTY-CAC applications to be available from the Start Menu. At a minimum, you must install the following packages:
   • putty.exe
   • pageant.exe
3. Verify the version of PuTTY that was installed by opening the application and clicking About in the lower left corner.

4. Launch pageant from the PuTTY install directory,(eg, C:\Program Files\Putty-CAC). Pageant will appear in the taskbar on the bottom right of your desktop;it will not open a window.

Insert CAPI Key into Pageant

1. Open Windows Explorer or click Start > Computer.
2. Open Pageant by clicking the executable.

3. A window will not open, but the Pageant icon will appear on the menu bar.

4. Right-click the icon and select View Keys.

5. The Pageant Key List window will appear. Click Add CAPI Cert.

6. Select your Smart Card Logon certificate from the Windows Security window.

Make sure you choose the correct certificate! Select“Click here to view certificate properties,” click “Details,” scroll half-way, and locate Enhanced Key Usage. It should begin with “Smart Card Logon”: this indicates it is the correct certificate. If you do not see this field, select a different certificate. Note: If multiple certificates exist, you may want to clear out the expired or revoked certificates by following [How To – PIV Card – Clear certificate store](FIXME:need URL).

7. Click OK to close the details window.
8. Highlight the correct Smart Card certificate and click OK.
9. The Pageant Window will now display the certificate information.
10. Click Close. Warning: You must re-add your certificate every time Pageant is started.

Configure PuTTY-CAC

1. Right-click the Pageant icon again from the menu bar and select New Session. This will launch PuTTY.

2. From within PuTTY, enter the destination IP address or hostname in the Host Name (or IP address) textbox to setup a new profile, or if you already have profiles set up in PuTTY, load that profile.

Note: If you have multiple destination profiles, you will have to do the following steps for each profile

3. Enter a descriptive name under Saved Sessions textbox (if setting up a new profile).

4. On left panel, select Connection > SSH > CAPI, then check the box beside the words Attempt CAPI Certificate (Key-only) auth (SSH-2).

5. From within PuTTY, select Connection > SSH > Auth then select both “Allow agent forwarding” and "Allow attempted changes of username in SSH-2.”

6. Click Session, then Save. This profile is now configured for PIV logon.

   

7. To get your PIV card’s SSH key, in PuTTY, go to Connection > SSH > CAPI and select the browse button on the right side. This will automatically fill in the “Cert” and “SSH keystring” fields.

8. Copy and paste the SSH keystring value from PuTTY into Notepad as you will need to include the SSH key when you contact the jumpbox support team or create a service ticket.

   **9. add how to add to authorized_users files

...and request that they add your PIV card’s SSH key to your account on the jumpbox and create a configuration file (as described below) for SSH key forwarding to other systems beyond the initial jumpbox. Include the IP address of the jumpbox you are using, your account name, and the SSH key derived from your PIV card. For other jumpboxes, submit a service ticket to that support group and include the IP address of the jumpbox you are using, your account name, and the SSH key derived from your PIV card.*\* The configuration file should contain “Host *” and “ForwardAgent yes” and exist in the same folder where they place the SSH key. 10. In Saved Sessions, click Save to save your configuration. ## Verify PIV Login 1. Open Pageant (if not already running) and make sure your CAPI key is populated , close the Pageant window. Right click the Pageant icon and choose “New Session”. This will open PuTTY-CAC .  2. Load one of your saved sessions that you previously configured for PIV logon. 3. When prompted, enter your remote Unix/Linux account name, and you should be prompted for your PIV PIN.  4. Enter your PIN, click OK and you should be logged in. 5. Once logged in, run ‘ssh-add –l’ to ensure that the forwarding agent is working. If you do not see the key printed when you run this command, something is wrong and you will not be prompted for your PIN if you ssh further into the environment.  6. Both the cert key that was pasted into the .ssh/authorized_keys and the config file need to be copied or scp’d to all the servers you will connect to in the data center. If the forwarding agent is working when you ssh to a server beyond the jumphost, you should be prompted for the PIN again. 7. After each server you ‘jump’ to, the output of ssh-add –l should always show the key. If not, either permissions are wrong or a file is mislabeled, or missing.

[lachellel]

Need to add the notes from NIH on what happens on the server (*nix) side....ala authorized_users mapping

[GSAllewell]

@lachellel : Where can I get that info?

[lachellel]

sent link @GSAllewell

Windows specific (puttyCAC)

for other interested parties, need the OpenSSH and Mac versions (specific to gov piv and cac).

[lachellel]

@GSAllewell i removed some email addresses etc from the baseline writeup

This one is common and simple to migrate to a page. raising the priority so we can clean up the verbiage, verify once more, and push it out.

[godadada]

@lachellel

I do not see putty/ssh files under piv-guides/pages directory. If one or more pages needed for ms/unix/mac ssh, do you have preference on the file names?

Thanks Chunde

[lachellel]

For now, let's draft it under developer guides for navigation (which we will rename):

• https://piv.idmanagement.gov/devconfig/
• this puts it in the _devconfig folder for a markdown file
• I started a placeholder and new branch (ssh) for you
• https://github.com/GSA/piv-guides/blob/ssh/_devconfig/ssh.md

We can always move it around.

[godadada]

@lachellel

Please confirm my following approach is okay:

1. review/edit the ms version above, removing all the graphic;
2. review/edit NIH version of ssh on linux;
3. research or create and review/edit ssh on Mac;

Thanks Chunde

[lachellel]

Yep. I'd start with 1 first, iterate, push, ask for feedback.

Then highlight modifications for 3 in a separate section.

1 and 2 are very similar - both using windows (jump boxes or dev workstations) to ssh to *nix, with different tools.

[godadada]

@lachellel

There are options on Mac version: SecureCRT, Putty-CAC for MAC, etc. Which one should be chosen?

[godadada]

Mac version and Linux version should be similar, if not the same, because MacOS is a flavor of Unix. But I do not have a way to test on a Mac for lack of platform.

[omar-nmi-ahmed]

Paul,

Can you get us access to a Mac for testing of code for the playbooks?

Omar.

[godadada]

A PIV card (certipath acess card can be substitute?), a card reader too.

[godadada]

There may be securtiy issue in downloading executable from the Internet, e.g. Win putty-CAC leading to https://github.com/NoMoreFood/putty-cac/releases. I am not sure it is safe to suggest gov users to download it to their machines. A more controlled designated download site may be better, e.g. a site managed by GSA.

[lachellel]

github is a versioned environment executables can be signed source code is available for review and local compiling and can be pulled in for code scanning

[rt-smithee]

Linux and Mac will differ in that SSH implementations on Linux likely will leverage OpenSSL and PKCS-11 under that to access the PIV card. I don't think Mac's do PKCS-11. (I believe they speak "CDSA" at that level...?)

[rt-smithee]

Also, there are several PIV card-equivalents available commercially. Happy to share suggested vendor names if that's appropriate here...

[godadada]

The non-Dod access to the github Putty-CAC softwere is not signed. We can create a signed version on github if decided.

[godadada]

@rt-smithee Thanks for the input. I am primarily interested in the UI of the Putty-CAC on Mac. I need document the difference if there is any. I need also to make sure it works with PIV card in Mac.

[rt-smithee]

Right and so all that stuff you find when you google "putty-cac" and it shows you dialog boxes to connect to CAPI/CNG or PKCS-11 do not work for your use case. Please, continue, definitely useful!

[godadada]

I am looking into installing Mac OS on VM machine, keep fingers crossed.

[lachellel]

From an iteration perspective, I'd do #1 first (windows), verify and push.

[godadada]

Hello,

Here is what I found potential candidate software for Smartcard login to SSH from Mac: PuTTYCAC: Windows, free, not viable PuTTYSC: Win, free, not viable SecureCRT: Win/Linux/Mac, not free MacGPG: Mac, free (example config: https://gpgtools.tenderapp.com/discussions/problems/12500-ssh-smartcard-authentication-with-macgpg)

I am pursuing and testing MacGPG. Let me know if you have any thing that may be helpful to me.

[lachellel]

i would stand down on this - let's discuss.

rodney's comments are spot on - it's not typically the client choice specifically, but the drivers and pkcs#11 configs. I would focus on explaining that particularly piece and options, and the client tools become more of a table.

[godadada]

Okay, I will put this one on hold for further decision.

FYI, MacGPG supports pkcs#11. testing may reveal if it is compatible with PIV card.

[rt-smithee]

Downloaded PuTTY-CAC per instructions, it was signed with a proper code signing certificate (the 64 bit MSI file.) Tried to use it with a test card using CAPI (CNG really) and it failed - claims SSH can't find a key with appropriate usage. IMO I have pilot errors here and I'm working to clean up my test. But... this concept you'd get an "appropriate usage" error might merit some documentation. Also the page at the very bottom makes a comment about then logging in to other systems with SSH - that assumes your SSH key management environment propagates keys and that might be specific to your site. I do see the "stand down" comment above, will make sure to sync with y'all before adding more to this thread. (I believe GPG uses a different applet and therefore won't talk to PIV cards. Nice to hear there's a PKCS-11, make sure it knows to talk to PIV not just GPG smartcards?)

[rt-smithee]

Just read the referenced "gpgtools support" path. IMO that will use a pkcs-11 shim that is specifically tuned to interact with a GPG smartcard so as to implement the SSH relevant public key operations. I would not expect that to work with PIV cards. For PIV cards you need a PKCS-11 shim that knows how to interact with the various keys/certs on the card via the PIV applet. The PKCS-11 shim inside OpenSC is an example of this.

[lachellel]

@rt-smithee the stand down comment is not to you! the pkcs11 comment was spot on and the real item that could use more explanation (in plainer language) so that engineers developing agency wide solutions for their IT users can understand the how and what. I meant 'stand down on going down a specific vendor path without explaining easily what to look for'

[godadada]

I was able to access PIV card from Mac with following installations. Will test it against SSH server. Install cackey: http://cackey.rkeene.org/fossil/wiki?name=Downloads Install opensc for MAC OS: http://github.com/OpenSC/OpenSC/wiki List pub keys on the inserted PIV: ssh-keygen -D /usr/local/lib/pkcs11/cackey.dylib

[godadada]

The listed keys do not look like from PIV. will look into it further.

[clstmbrly]

@lachellel In a previous comment about SSH Playbook, you said "there is no navigation to help the reader find the information." Just checking to ensure I understand correctly. You would like a TOC added to each of the 4 major sections (OS sections and the "Configure UNIX-like Server" section) so the reader can jump to subsection topics? (There is currently only a top-level TOC that links to the 4 major sections.) Thanks!

[indrajit-gsa]

@clstmbrly @lachellel I have updated the write-up for SSH playbook and tested from Windows to 3 different Linux flavored servers. I also added 2 screenshots. I added some context for Mac OS versions and left the instructions for older versions for now which require a software for PIV/CAC. I removed login from *nix desktops for now. Please review.

The content link is - https://github.com/GSA/piv-guides/blob/ssh/_engineering/02_ssh.md

[clstmbrly]

@lachellel Is it more likely that an engineer will use a Mac, rather than a computer running another Linux-based OS (e.g., Debian, etc.)?

[clstmbrly]

@lachellel SSH is ready for your review: https://github.com/GSA/piv-guides/blob/ssh/_engineering/02_ssh.md. Have a great weekend:-).

[clstmbrly]

@lachellel There were some rendering issues with spacing, indention, and numbering that I couldn't resolve.