Key Generation and Attestation with Yubikey

For the purposes of EV 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. SSL.com optionally ships EV code signing and PDF document signing certificates pre-installed on FIPS 140-2 validated security key USB tokens, but users can also 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 order certificates from SSL.com that may be installed manually on the YubiKey.

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

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.
   
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’s management key, then click OK. If you need your management key, please contact Support@SSL.com.
    
13. Enter your YubiKey PIN, then click OK. If you need help finding your PIN, please refer to this how-to.
    
14. The CSR file will be saved in the place you specified in step 11, above. 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 command line.

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:
   • 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 an attestation certificate for the key with the command below (replace ATTESTATION-FILENAME.crt with the path and filename you want to use; if you used slot 9c, replace 9a with 9c):
   • Windows:

     .\ykman.exe piv keys attest 9a ATTESTATION-FILENAME.crt

   • 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 (replace INTERMEDIATE-FILENAME.crt with the path and filename you want to use):
   • Windows:

     .\ykman.exe piv certificates export f9 INTERMEDIATE-FILENAME.crt

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