Historique de la page

This documentation assumes that you have used ssh keys in the past.  The YubiKey 

This is a step-by-step on how to setup SSH user certificates using PIV for hardware-backed keys.

Windows

1. Download from Yubico website https://www.yubico.com/products/services-software/download/yubikey-manager/ 

   1. Yubikey Personalization gui tool

      NOTE: You do not need to download the personalization GUI tool if you are only looking to load authentication certs

   2. Yubikey NEO Manager Tool
   3. Yubikey PIV Manager tool 
2. Run the Yubikey NEO Manager and insert your key.  
   1. Click Change Name and change the name to something recognizable.
   2. The name you set is only stored locally on your computer; it's there to make it easier to tell the difference between multiple Yubikeys in the NEO Manager.
   3. Image Removed
   4. Click Change connection mode  and select CCID (need for PIV/certificates). You can leave U2F and OTP if you are using them, or turn them off.
   5. Image Removed
   6. Remove the key when prompted and reinsert.
3. Insert key and log in or Run the Yubikey PIV Manager tool as the user account you are adding a PIV cert.  
   1. Enter a PIN.  The PIN must be 4-8 characters in length and can contain capital and lowercase letters, numbers, and special characters (!, @, #, etc.).
   2. Image Removed
   3. Select Use a separate key and then click Random.  Record this Management key. You will need it later on to add certificates.
   4. Enter a PUK (Personal Unlocking Key) and Click OK
   5. Click Certificates and then choose the tab you want to add the certificate to (Authentication, Digital Signature, Key Management, Card Authentication)
      1. Image RemovedImage Removed
         
      2. Click Generate new key
      3. Image Removed
         
      4. Select RSA (2048)
      5. Select Request a certificate from a Windows CA
         1. Enter Certificate Template (yubicosc for Main, FinanceSmartcard for Finance)
         2. For Subject, enter your AD Account's DistinguishedName, but replace the commas with slashes. This is CASE SENSITIVE.
            1. You can get this for the user you're currently logged in as by running the PowerShell command:

               1. "/"+(get-aduser -server main.ad.rit.edu $env:USERNAME).distinguishedname.replace(",","/")

                  1. Example: /CN=jlgdss/OU=Other/OU=AMS/OU=Users/OU=RITusers/DC=main/DC=ad/DC=rit/DC=edu

            2.  "/"+([adsisearcher]::new("samaccountname=$env:USERNAME").FindAll().Properties.distinguishedname).replace(",","/")
                
         3. Click OK
         4. Enter PIN you just created (same for all certs) when prompted.
         5. Enter Management Key if prompted.
         6. Choose RIT AD Signing CA (Kerberos) - itscaad01.ad.rit.edu
            
         7. It should then say a new private key has been generated.
            
4. If you want to load certificates for another account (ex. a "-admin" account):
   1. Close the PIV manager
   2. Run the PIV manager as the account you want to generate a certificate for
      
   3. Select another tab/slot that does not already have a certificate assigned – only slots 1 (the 'authentication' tab), 3 ('the 'key management' tab), and 4 (the 'card authentication' tab) support smart card authentication by pin

   4. Perform the same steps starting with Generate Key above

      See Using Certificate for Digitally Signing Email in Outlook if you want to digitally sign your emails with your new certificates.

OS X or Linux

Prerequisites

• a YubiKey with the PIV application loaded

• the yubico-piv-tool software

• the ykcs11 PKCS#11 module

• OpenSSH

Steps

1. Generate an "ssh user CA" key and trust it for this account on this host

   ssh-keygen -N '' -C user-ca -f ~/.ssh/ca
   sed 's/^/cert-authority /' ~/.ssh/ca.pub > ~/.ssh/authorized_keys
   

2. Generate or import a key in PIV slot 9c that requires touch.

   yubico-piv-tool -a generate -s 9c -A RSA2048 --pin-policy=never --touch-policy=always -o public.pem
   yubico-piv-tool -a selfsign-certificate -s 9c -S "/CN=SSH key/" -i public.pem -o cert.pem
   yubico-piv-tool -a import-certificate -s 9c -i cert.pem

3. Double check that the key appears in slot 9c (optional)

   yubico-piv-tool -a status
   

4. Clear the SSH agent

   ssh-add -D
   ssh-add -e /PATH/TO/libykcs11.so
   

   • Make sure to use the correct path (e.g. /usr/local/lib) and extension (.so for Linux, .dylib for Mac OS X) for libykcs11.

   • Beware that ssh-add -D doesn’t seem to clear PKCS#11 libraries, only keys.

5. Add PIV to the SSH agent (will prompt for PIV PIN)

   ssh-add -s /PATH/TO/libykcs11.so
   

6. Get the public key from PIV and sign it using the CA key. This produces ~/.ssh/id_rsa-cert.pub

   ssh-add -L > ~/.ssh/id_rsa.pub
   ssh-keygen -s ~/.ssh/ca -I identity -n "${LOGNAME}" ~/.ssh/id_rsa.pub
   

7. Authenticate to the target system using the new key:

   ssh user@sporcsubmit.rc.rit.edu
   

If you have followed these steps to the letter, you will not be asked for the PIV PIN, but your YubiKey will start blinking, waiting for touch.

More info

Yubikey SSH - https://developers.yubico.com/PIV/Guides/SSH_user_certificates.html

Manual - https://www.yubico.com/wp-content/uploads/2015/03/YubiKeyManual_v3.4.pdf

Software:

https://developers.yubico.com/yubikey-piv-manager/Releases/

https://developers.yubico.com/yubikey-personalization-gui/Releases/

...

wiki page is deprecated. You can find this documentation on our new documentation site: https://research-computing.git-pages.rit.edu/docs/configuring_ssh_with_yubikey.html