Key Generation and Attestation with Yubikey

For the purposes of code signing and Adobe PDF digital signatures, it is required that your private key be securely generated and stored on an external FIPS-validated hardware device rather than your computer. Users can generate a key pair on an existing YubiKey and an attestation certificate that proves that the private key was generated on the device. The attestation certificate can then be used to obtain certificates from SSL.com that may be installed manually on the YubiKey.

An attestation certificate is only valid for one YubiKey. If you need to install your certificate in multiple YubiKeys, you will have to perform an attestation for each token. Please contact support@ssl.com to get more details about multiple issuances of a certificate.

This how-to will walk you through:

• Generating a key pair and attestation certificate on on your Yubikey
• Verifying the attestation certificate and associating it with an SSL.com EV code signing or PDF document signing order
• Installing your new certificate in the YubiKey

Requirements

1. Latest version of Yubikey Manager installed. 
2. A Yubikey with a configured PIN and PUK: https://docs.yubico.com/yesdk/users-manual/application-piv/pin-puk-mgmt-key.html
   
   1. If your YubiKey was ordered from SSL.com and you need to replace an expired signing certificate. you can refer to your PIN and PUK by logging in to your SSL.com account. Click the Orders tab, locate your certificate order and click the download link to display the details of your certificate. Scroll down to the physical tokens section where the values for your YubiKey’s PIN and PUK are indicated. Make sure to also save your PIN and PUK on a Password Manager.
      
   2. If your Yubikey token was purchased from Yubico, you will need to set your PIN and PUK. To do this, open Yubikey Manager and click the Applications tab. Select PIV. Under the PIN Management section, click the Configure PINS button. 
      
      

Step 1: Generate Key Pair on YubiKey

1. If you have not done so already, download and install YubiKey Manager from Yubico’s website. Versions for Windows, Linux, and macOS are available.
   
2. Plug in your YubiKey, then launch YubiKey Manager. Your YubiKey should be displayed in the YubiKey Manager window.
   Note: If your token is not being displayed on Yubikey Manager, try to close the application. Right-click it with your mouse, and choose Run as an administrator.
   
3. Navigate to Applications > PIV.
   
4. Click the Configure Certificates button.
   
5. Select the tab for the YubiKey slot where you would like to generate the key pair. If you are buying an EV code signing certificate, choose Authentication (slot 9a). For PDF document signing, choose Digital Signature (slot 9c). (See Yubco’s documentation for more information on the various key slots and their intended functions; they differ in their PIN entry policies). Here we are going to use slot 9a.
   
6. Click the Generate button.
   
7. Select Certificate Signing Request (CSR), then click the Next button.
   
8. Select an Algorithm from the drop-down menu. For document signing, choose RSA2048. For EV code signing, choose ECCP256 or ECCP384.
   
9. Enter a Subject Name for the certificate, then click the Next button.
   
   Note: We won’t actually be using this CSR—it’s generated as a byproduct of creating a new key pair. So, it doesn’t really matter what you enter for the Subject Name here.
   
   Users must ask SSL.com for a new issuance when submitting a new order, the issuance will not happen automatically.
10. Click the Generate button.
    
11. Select a location to save the CSR file, create a filename, then click the Save button.
    

12. Enter your YubiKey PIN, then click OK. If you need help finding your PIN, refer to the instructions provided in the Requirements section at the top of this article. 

    
13. The CSR file will be saved in the place you specified in step 11, above. Yubikey Manager will also flash a message indicating the CSR was successfully generated. Again, we don’t need this file to proceed and you can safely delete it.
    

Step 2: Generate Attestation Certificate

Each YubiKey comes pre-loaded with a private key and certificate from Yubico that allows you to generate an attestation certificate to verify that a private key has been generated on a YubiKey. This operation will require you to use the ykman Command Line Interface (CLI) that is installed when you download Yubikey Manager.

1. In Windows, open PowerShell as an administrator. macOS and Linux users should open a terminal window on their device.
   
2. Use the following command to navigate to the YubiKey Manager files and access ykman
   
   • Windows:

     cd "C:\Program Files\Yubico\YubiKey Manager"

   • macOS:

     cd  /Applications/YubiKey\ Manager.app/Contents/MacOS

   • On Linux (Ubuntu), the ykman command will already be installed in your PATH, so you can skip this step.
3. Using PowerShell, the command below will generate an attestation certificate. Choose/create a folder in your computer where you want the attestation certificate to be stored and then think of a name you want to use for the certificate. Make sure to choose names that are simple and single-worded to avoid errors when entering the command on PowerShell. For example, the name of your folder could be attestation and the name you want to use for the attestation certificate could be attestationfilename. The path that you would include in the command would then be something like: C:\Folder\Folder\attestation\attestationfilename. After entering the command on PowerShell, check in your chosen computer folder if the attestation certificate was successfully generated. 
   
   • Windows:

     .\ykman.exe piv keys attest 9a C:\Folder\Folder\attestation\attestationfile

   • Linux (Ubuntu):

     ykman piv keys attest 9a ATTESTATION-FILENAME.crt

   • macOS:

     ./ykman piv keys attest 9a ATTESTATION-FILENAME.crt

     
4. Next, use the ykman command to export the intermediate certificate from slot f9 of the YubiKey. Choose/create a folder in your computer where you want the intermediate certificate to be exported. Replace C:\Folder\Folder\attestation\intermediatefilename with the path and filename you want to use):
   • Windows:

     .\ykman.exe piv certificates export f9 C:\Folder\Folder\attestation\intermediatefilename

   • Linux (Ubuntu):

     ykman piv certificates export f9 INTERMEDIATE-FILENAME.crt

   • macOS:

     ./ykman piv certificates export f9 INTERMEDIATE-FILENAME.crt

Step 3: Verify Attestation Certificate with SSL.com and Attach to Order

1. Here we are going to use our attestation certificate from YubiKey slot 9a with an EV code signing certificate order. (The procedure for document signing certificates is the same.) First, open the attestation and intermediate certificates in a text editor.
   
2. Login to your SSL.com user account and navigate to the Orders tab, then click the details link for the order you wish to associate with the attestation certificate. (This link will change to download after your certificate is issued.)
   
   Note: If you wish to check the validity of your attestation certificate without attaching it to an order, you can use SSL.com’s attestation verification tool.
   
3. Click the manage link, under attestation.
   
4. A new page with fields for the attestation and intermediate certificates will appear.
   
5. Paste the attestation certificate into the Attestation Certificate field, making sure to include the lines -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----.
   
6. Next, paste the intermediate certificate into the Intermediate Certificate field.
   
7. Click the Submit button.
   
8. If everything has gone correctly, a green alert will appear at the top of the screen, indicating a successful attestation.
   
9. Return to the order in your account. You can verify that the attestation has been added to the order by the presence of a link labeled Delete under attestation.
   
10. After SSL.com processes your order, the certificate will be available in your SSL.com account. From your order details page, scroll down to END ENTITY CERTIFICATES section and click Show Details.
    
11. Scroll down to the subsection labeled Code Signing Certificate or Document Signing Certificate, depending on your order. To the right, you will see the download links for your certificate.
    
    1. If you have a Document Signing Certificate, choose the individual certificates download option. This is a zip file containing three certificate files: your end-entity certificate, an intermediate certificate, and a root certificate.
       
       
    2. If you have a Code Signing Certificate, choose the for YUBIKEY installation (DER).
       
12. Expand the zip file. There should be three certificate files: your end-entity certificate, an intermediate certificate, and a root certificate.
    

Step 4: Install Certificate in YubiKey

1. Launch YubiKey Manager and mavigate to Applications > PIV.
   
2. Click the Configure Certificates button.
   
3. Select the tab for the same YubiKey slot where you generated the key pair.
   
4. Click the Import button.
   
5. Navigate to your end-entity certificate file and click the Import button.
   
6. Enter your YubiKey’s management key, then click OK. If you need your management key, please contact Support@SSL.com.
   
7. The new EV code signing certificate is installed in the YubiKey.
   
8. To make sure your digital signatures are trusted on all computers, you should also install the root and intermediate certificates on your YubiKey for a complete chain of trust. Please follow these instructions for root and intermediate installation: Install SSL.com Root and Intermediate Certificates on YubiKey.
9.  Optional step: If you are a customer who replaced an expired certificate in your Yubikey, you will also need to delete the copy of the expired cert that is still in the Windows certificate store. To do this, type certmgr on the Windows search bar of your computer. Next, click Manage computer certificates. Click the Personal folder, locate the expired signing certificate, right-click it with your mouse, and choose Delete.