Smart Card Logon for SSH

For network engineers, this guide will help you authenticate with your PIV/CAC credential and use SSH to access a remote Linux server from a Windows or macOS computer. For server administrators, this guide will help you configure a Linux server for remote access.

This guide uses open-source options:

• Windows: PuTTY-CAC (without Pageant) and WinSCP with Pageant
• macOS: OpenSC

Commercial solutions are also available.

SSH from Windows

SSH Using PuTTY-CAC

PuTTY-CAC is an open-source SSH client that uses Microsoft’s CryptoAPI (CAPI). (Pageant isn’t needed with PuTTY-CAC for this solution.)

1. You’ll need to download PuTTY-CAC to C:\ssh\putty.exe or a similar folder. Select either 32-bit or 64-bit, based on your Windows OS. (Pageant and MSI Installers aren’t needed.)
2. Double-click on putty.exe and insert your PIV/CAC card into your card reader.
3. At the PuTTY Configuration window, go to Category: > Connection > SSH > Certificate. Click the Set CAPI Cert… button and OK.
   
   
   
   
4. From the Windows Security list, select your PIV/CAC authentication certificate by clicking OK. If you don’t see your certificate, click More choices. (For help with certificates, see Understanding PIV Certificates.
   
   
   

5. Back at the PuTTY Configuration window, click the Copy to Clipboard button and paste the SSH key into a text file. (Note: PuTTY-CAC derives the SSH key from the public key of your authentication certificate.) The SSH key will look like this:

      ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCyPn2dShOF...
      CAPI:05bf4653b3098a87b67816d81049f489d5b5ffb4
   

6. Send the text file to the server administrator and request an account. (Notice that the Attempt Certificate Authentication box is now checked.)
   
7. While waiting for an account, you can create SSH session profiles for target remote servers:
   
   • Click Session and enter a remote server’s hostname or IP address.
     
   • For Connection type, click SSH. (Notice that under Port, 22 appears.)
     
   • Enter a session name in Saved Sessions and click Save.
     
8. Once you have an account, open PuTTY-CAC and insert your PIV/CAC card into your card reader.
9. Click a Saved Session and Load.
10. Click Open to connect to the remote server. (A dialog box displays the server’s key thumbprint.)
11. Verify the server key and accept it by clicking Yes.
12. Enter your account username. (A dialog box displays your PIV/CAC authentication certificate.)
13. Click Yes to permit the signing operation and enter your PIV/CAC PIN. (You’ll then be logged into the remote server.)

SSH Using WinSCP and Pageant

WinSCP is an open-source, secure copy protocol (SCP) and secure file transfer protocol (SFTP) client. Pageant is an SSH authentication agent that uses Microsoft’s CAPI.

1. Download Pageant to C:\ssh\pageant.exe or a similar folder. Select 32-bit or 64-bit, based on your Windows OS.
2. Download the WinSCP installer to C:\ssh\WinSCP-Setup.exe or a similar folder.
3. Double-click WinSCP-Setup.exe to launch the WinSCP installer and use the recommended installation settings.
4. Double-click pageant.exe to launch Pageant.
5. Next, at the Windows taskbar, click the up-arrow and right-click the Pageant icon (computer wearing a Fedora).
   
   
6. A Pageant dialog box appears. Click Cert Auth Prompting.
   
   
7. Click Add CAPI Cert to view eligible authentication certificates.
   
   
8. From the Windows Security screen, select your PIV/CAC authentication certificate, and click OK. If you don’t see your certificate, click More choices. (For help with certificates, see Understanding PIV Certificates.)
   
   
9. Double-click the Pageant icon to confirm that your certificate appears on the Pageant Key List.
10. The Pageant Key List shows the certificate’s SSH key attributes, such as type, size, thumbprint, etc. Click your certificate and the Copy to Clipboard button. (Note: Pageant derives the SSH key from the public key of your authentication certificate.) Close the Pageant Key List.
    
    
11. Paste the SSH key into a text file. It will look like this:

       ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCOpGPxNh... CAPI:268f09f34ca7544bd44e1e310d2144...
       OID.0.9.2342.19200300.100.1.1=47999999999999 + CN=SAM JACKSON, OU=General Services Administration,
       O=U.S. Government, C=US
    

12. Send the text file to the server administrator and request a new account.
13. Once you have an account, go to the WinSCP Login window. Click New Site and then the Advanced button.
    
    
    
    
14. At the Advanced Site Settings window, select SSH > Authentication. Click the checkbox for Attempt Authentication using Pageant and then click OK. (WinSCP selects additional checkboxes by default.)
    
    
    
    
15. Insert your PIV/CAC card into your card reader.
16. Enter the remote server’s host name and your username. Click Login.
17. The Warning dialog box displays the server’s key thumbprint. Verify it and click Yes to accept.
18. At the Certificate Usage Confirmation - Pageant dialog box, click Yes to confirm your authentication certificate.
    
    
    
    
19. When prompted, enter your PIV/CAC PIN. You’ll then be logged into the server.

SSH from macOS

There are two options for configuring SSH clients to use a PIV/CAC device as the SSH key store:

Built-in PIV/CAC support

Only applicable for macOS High Sierra and later.

1. Insert your PIV/CAC into your card reader.
2. Use ` ssh-keygen -D /usr/lib/ssh-keychain.dylib to get the OpenSSH-format public key fingerprint which can be added to your authorized_keys` file, account profiles, etc.
3. Add PKCS11Provider=/usr/lib/ssh-keychain.dylib to your ~/.ssh/ssh_config file to tell ssh to scan the PIV profiles for keys when determining which keys to attempt on remote hosts.

See https://support.apple.com/en-us/HT208372 for additional information

OpenSC

You can use OpenSC on your macOS computer to authenticate to a remote server with your PIV/CAC card.

1. Install OpenSC.
2. Insert your PIV/CAC into your card reader.
3. To view the certificates on your Mac, enter:

    pkcs15-tool --list-public-keys  
   

4. Make note of the PIV AUTH pubkey  ID number.

    Using reader with a card: SCR35xx Smart Card Reader
    Public RSA Key [PIV AUTH pubkey]
        Object Flags   : [0x0]
        Usage          : [0xD1], encrypt, wrap, verify, verifyRecover
        Access Flags   : [0x2], extract
        ModLength      : 2048
        Key ref        : 154 (0x9A)
        Native         : yes
        ID             : 01 (EXAMPLE ONLY)
        DirectValue    : <absent>
   

5. Use your PIV AUTH pubkey  ID number to view your SSH key. Enter:

    pkcs15-tool --read-ssh-key 01
   

6. When prompted, enter your PIV/CAC PIN. The SSH key will look like this:

    ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCyPn2dShOFLBnMraiP2MnLU ....  
   

7. Copy the SSH key and paste it into a text file.
8. Send the text file to the server administrator and request a new account.
9. Once you have an account, you can log into the remote server. Enter:

    ssh -I /usr/lib64/opensc-pkcs11.so <username>@<remote-host>
   

10. Optionally, you can update the setting in the /etc/ssh_config file to:

    PKCS11Provider /usr/lib64/opensc-pkcs11.so
    

11. Enter your PIV/CAC PIN when prompted. Once it’s validated, you’ll be logged into the remote server.

Configure a Linux Server

By default, SSH keys are read from the .ssh/authorized_keys file in your home directory.

1. You’ll need to create a /home/<username>/.ssh directory and change it to the requester’s ownership. Then, create an authorized_keys file in the .ssh directory and copy the requester’s SSH key to the /home/<user>/.ssh/authorized_keys file starting with ssh-rsa<public key><key_name>:

        mkdir /home/<user>/.ssh
        chown <user> .ssh
        chgrp <user> .ssh
        chmod 700 .ssh
        cat > authorized_keys 
        ssh-rsa AAAAB3NzaC1yc2EAAAADAQA... CAPI:05bf4653b3098a87b67816d81049f489d5b5ffb4    
   

2. Set the permissions for …authorized_keys to 600 and change the authorized_keys ownership to the user:

         chmod 600 authorized_keys
         chown <user> authorized_keys
         chgrp <user> authorized_keys
   

3. You can change the location for the authorized_keys file in the /etc/ssh/sshd_config file and restart the sshd service. You can also enforce authentication with a PIV/CAC card by disabling password use:

         AuthorizedKeysFile /etc/ssh/authorized_keys/%u  
         PasswordAuthentication no
   

   Note:  If you change the default settings, you’ll need to create a corresponding directory for authorized_keys under /etc/ssh and place the authorized_keys there vs. in the user’s home folder.

Special Thanks

Special thanks to the Department of Homeland Security, Office of the Chief Information Officer, Identity Services Branch, Information Sharing and Services Office (IS2O), for sharing its WinSCP and Pageant procedures.