Skip to main content
U.S. flag

An official website of the United States government

Dot gov

The .gov means it’s official.
Federal Government websites often end in .gov or .mil. Before sharing sensitive information, make sure you’re on a Federal Government site.

Https

The site is secure.
The https:// ensures that you are connecting to the official website and that any information you provide is encrypted and transmitted securely.

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.

Your PIV/CAC credential contains an authentication certificate key pair (public and private) for smart card logon. Using a PIV/CAC key pair is very similar to using a self-signed key pair for SSH.

Your Chief Information Security Officer must determine that security controls are in place and approve SSH scenarios. You should also review your agency’s policies and use your physical or virtual jump servers to restrict users from using SSH directly from workstations.

SSH from Windows

Network administrator privileges are needed to use SSH for remote access.

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.

    PuTTY configuration window.

  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.

    A PuTTY select certificate for authentication screenshot.
  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.)

The card reader may flash. Do not remove your card until you’re logged in.

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).
    A screenshot showing how to access pageant.
  6. A Pageant dialog box appears. Click Cert Auth Prompting.
    Enable Cert Auth Prompting.
  7. Click Add CAPI Cert to view eligible authentication certificates.
    A screenshot showing Add CAPI Cert selected.
  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.)
    A screenshot showing a PuTTY select certificate for authentication window with the OK button selected.
  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.
    A screenshot showing a 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.

    A screenshot showing the WinSCP Login window with the Advanced button selected.

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

    A screenshot showing the Advanced Site Settings window with SSH, Authentication, and Attempt authentication using Paegent options selected.

  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.

    A screenshot showing the Certificate Usage Confirmation - Pageant window with the Yes button selected.

  19. When prompted, enter your PIV/CAC PIN. You’ll then be logged into the server.

The card reader may flash. Do not remove your card until you’re logged in.

SSH from macOS

Network administrator privileges are needed to use SSH for remote access.

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.

Use OpenSC Version Greater Than 0.20.0 to avoid Authentication Errors

If a version of OpenSC less than 0.20.0 is used, users will encounter errors when performing mTLS with servers that offer TLS 1.3. This can include browser errors like ERR_SSL_CLIENT_AUTH_SIGNATURE_FAILED.

  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.

The card reader may flash. Do not remove your card until you’re logged in.

Configure a Linux Server

Server administrators must have root privileges for these steps.

The following SSH configurations are examples only. Other options are available, including Pluggable Authentication Modules (PAM) that look up user accounts and authorizations through directories. You can automate account setups by using centralized configuration management tools that can push or remove authorized_keys.

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.

IDManagement.gov

An official website of the U.S. General Services Administration

Looking for U.S. government information and services?
Visit USA.gov Edit this page