Key Generation and Attestation with YubiKey for Code Signing Certificates

For the purposes of code signing, 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 code signing 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 your Yubikey
• Verifying the attestation certificate and associating it with an SSL.com EV code signing order
• Downloading your code signing certificate
• Installing your new certificate in the YubiKey

Requirements

1. Latest version of Yubico Authenticator and ykman Command Line Interface (CLI). 
   
   Note:
   
   To generate the key pair and later on install the code signing certificate, download this tool: Yubico Authenticator Graphical User Interface (GUI). 

   To generate the attestation certificate, use the ykman Command Line Interface (CLI) which is included in this download package: YubiKey Manager.
   
   Upon installation, both of these tools will be stored in your computer’s Yubico folder.
   
   

2. Your YubiKey PIN and PUK configured on Yubico Authenticator. If your YubiKey token was purchased from Yubico, you will need to set your PIN and PUK. To do this, open Yubico Authenticator, click the Certificates tab. On the Manage section, you will see the options to configure your PIN and PUK. 
   

Step 1: Generate Key Pair on YubiKey

1. Download Yubico Authenticator.
   
   
2. Plug in your YubiKey, then launch Yubico Authenticator.
   
   
3. Under the Certificates section, select the tab corresponding to the YubiKey slot where you intend to generate the key pair. For a code signing certificate, select Authentication (slot 9a). Click on Generate Key to proceed.
   

4. On the Subject field, place the distinguished name (DN) for the code signing certificate. This is the name of the organization or individual and will be displayed on any software that has been signed using the certificate. Make sure to type the characters CN= before typing the distinguished name. Example: CN=Example Company.

   For Output Format, choose Certificate Signing Request (CSR).

   From the Algorithm drop-down list, make a selection. For code signing, opt for ECCP256 or ECCP384.
   
   Finally, click the Save button.
   
   
5. Save the CSR certificate in a folder.
   

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) which is located in the YubiKey Manager folder of your computer. To be able to access ykman CLI, you will need to use Windows PowerShell as demonstrated in the following steps.

1. In Windows, open PowerShell as an administrator. macOS and Linux users should open a terminal window on their device.
   

2.  Use the cd (Change Directory) command to navigate to the YubiKey Manager files and access ykman. To do this on Windows, do the following by order, on the same line on Powershell:
   
   Type cd on PowerShell
   Press space
   Copy the folder path where ykman is located, then enclose it in double quotation marks. Example: "C:\Program Files\Yubico\YubiKey Manager"
Press Enter
   

   • 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. Generate the attestation certificate. After switching to ykman using Powershell, use the command below to generate an attestation certificate which will be in the form of a text file. On Windows, the command will look like this: .\ykman.exe piv keys attest 9a C:\Folder\Folder\attestation\attestationfilename
   
   Let us break it down:
   
   a.  Copy this to Powershell: .\ykman.exe piv keys attest 9a 
   
   b. On the same line on Powershell, copy the folder path where you want to store the attestation certificate. Choose/create a folder in your computer.  Example: C:\Folder\Folder\attestation.
   
   Make sure to choose/ create folders that have single word names or no space to avoid errors when entering the command on PowerShell. 
   
   c. Think of a name you want to use for the certificate. At the end of the folder path you copied to PowerShell, add a backslash (\)  and the name you want to use for your attestation certificate. Example:\attestationfilename 
   
   Make sure to generate a file name that has no special characters and no space to avoid errors when entering the command on PowerShell. 
   
   d. Press Enter on PowerShell to finally generate the attestation certificate text file.
   
   After entering the command, check in your designated computer folder if the attestation certificate was successfully generated. It will be in the form of a text file and bear the name you set for it. When opened, it will display a body of letters and numbers headed by —–BEGIN CERTIFICATE—– at the top and —–END CERTIFICATE—– at the end.
   
   
   • Windows:

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

   • Linux (Ubuntu):

     ykman piv keys attest 9a ATTESTATION-FILENAME.crt

   • macOS:

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

4. Export the intermediate certificate. Next, use the ykman command to export the intermediate certificate from slot f9 of the YubiKey. The certificate will be in a text file format. The command will look like this: .\ykman.exe piv certificates export f9 C:\Folder\Folder\attestation\intermediatefilename
   
   Let us break it down: 
   
   a. Copy this to PowerShell: .\ykman.exe piv certificates export f9
b. Choose or create a folder in your computer (i.e.  Documents) where you want the intermediate certificate to be exported. Copy the folder address to PowerShell.  Example: C:\Folder\Folder\attestation
   c. Create a file name for the intermediate certificate. Add a backslash before the name and append it at the end of the folder address you have copied to PowerShell, with no space in between. Example: \intermediatefilename
   d. Press Enter. Once you enter the command, the intermediate certificate will appear in the designated folder, bearing the name you set for it. When opened, it will display a body of letters and numbers headed by —–BEGIN CERTIFICATE—– at the top and —–END CERTIFICATE—– at the end. 
   
   
   • • 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. 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. Click the link labeled details (for new orders) or download (for old orders) for the order you wish to associate with the attestation certificate. (This link will appear as download for customers with an expired signing certificate that they want to replace).
   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. Select your use case below:
   a. For customers with a blank YubiKey, click the manage link, under attestation.
   b. For customers replacing an expired signing certificate, click the Delete link first to remove the previous attestation submission for your expired signing certificate. Afterward, click the manage link.
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.

Step 4: Download your Code Signing Certificate

1. Once SSL.com approves your attestation and issues your certificate, you can now download it. To do this, log in to your SSL.com account and click Orders from the top menu. Locate your order from the list and click the download link. 
   
2. When the download page is displayed, scroll down to END ENTITY CERTIFICATE section.  Click the accordion arrow to display your certificate details. To the right you will see the download format options available. Choose individual certificates and click the Download button. This is a zip file containing three certificate files: your end-entity certificate, an intermediate certificate, and a root certificate. Later, you will only need to import the end-entity certificate in your YubiKey. 
   
3. Extract the downloaded zip file.
4. Choose where to extract the files and then click the Extract button.
5. Open the folder containing the extracted certificates. You will see three certificates but you will only need to install your end-entity certificate which is a .CRT file and bears the name of the person or organization. From here, you are now ready to install your certificate.
   

Step 5: Install Certificate in YubiKey  

1. Open Yubico Authenticator
   
   
2. Click Certificates, followed by 9a Authentication, and Import file.
   
3. Enter your YubiKey PIN when prompted.
   
4. Navigate to the folder where the certificates were extracted and click your end entity code signing certificate.
   
5. Yubico Authenticator will display the details of your code signing certificate. Click Import button.
   
   
6. Your certificate is now successfully installed.
   
7. 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.
   

Code Signing Attestation Troubleshooting 

If SSL.com rejects your attestation submission, it is due to one of the following

1. Step 1: Generate Key Pair on YubiKey
   1. Your Certificate Signing Request (CSR) is being rejected by Yubico Authenticator
      • You have to  include the characters CN= on the Subject field. Yubico Authenticator will reject the CSR if this is not done. 
      • You have to choose ECCP256 or ECCP384 for the algorithm. These two types are the only ones acceptable for a code signing certificate.
        
        
2. Step 2: Generate Attestation Certificate
   1. You can’t access ykman CLI
      • You cannot access ykman by double-clicking the icon for the application on YubiKey Manager. You can only use it by first opening a shell application like PowerShell, then using the Change Directory (cd) command to run it. 
      • When typing the cd command on PowerShell, there should be a space between cd and the folder path of ykman CLI. Example: cd “C:\Program Files\Yubico\YubiKey Manager”
      • The ykman CLI folder path should be enclosed in double quotation marks. Example: “C:\Program Files\Yubico\YubiKey Manager”
   2. The attestation and intermediate certificates are not being generated
      • Make sure to choose/ create folders that have single word names or no space to avoid errors when entering the command on PowerShell.  
      • Make sure to generate a file name that is short and single-worded with no special characters to avoid errors when entering the command on PowerShell.  
        
        
3. Step 3: Verify Attestation Certificate with SSL.com and Attach to Order
   1. The attestation and intermediate certificates are failing to be submitted on my SSL.com account
      • When opening them on a text editor like Notepad, make sure to copy the entire contents of the file including —–BEGIN CERTIFICATE—– at the top and —–END CERTIFICATE—– at the end. 

Related Guides to Signing Code with your YubiKey

1. Using Your Code Signing Certificate: Learn how to sign applications using your OV or EV code signing certificate with Microsoft SignTool.