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.

Do not follow these instructions if you ordered a YubiKey along with your certificate from SSL.com, as these YubiKeys are shipped with certificates pre-installed. This how-to is for customers who want to install certificates on a YubiKey FIPS that they already own.

This how-to will walk you through:

Note: The screenshots below are from Windows, but the procedures are almost identical on Linux and macOS. Differences between platforms are noted below. Linux instructions refer to Ubuntu 19.10, with YubiKey manager installed with apt-get (see Yubico’s instructions for more information). A Linux AppImage is also available from the YubiKey Manager download page. Also note that while these instructions use Yubico’s Yubikey Manager software, the 3.0 release of SSL.com’s SSL Manager supports keypair generation and certificate installation on YubiKey for Windows users.

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.
    YubiKey Manager Download
  2. Plug in your YubiKey, then launch YubiKey Manager. Your YubiKey should be displayed in the YubiKey Manager window.
    YubiKey Manager
  3. Navigate to Applications > PIV.
    Applications > PIV
  4. Click the Configure Certificates button.
    Configure Certificates
  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 Yubico’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.
    Authentication (slot 9a)
  6. Click the Generate button.
    Generate
  7. Select Certificate Signing Request (CSR), then click the Next button.
    Certificate Signing Request (CSR)
  8. Select an Algorithm from the drop-down menu. For document signing, choose RSA2048. For EV code signing, choose ECCP256 or ECCP384.
    select algorithm
  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.
    Subject Name
    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.
    generate
  11. Select a location to save the CSR file, create a filename, then click the Save button.
    Save CSR
  12. Enter your YubiKey’s management key, then click OK. If you need your management key, please contact Support@SSL.com.
    management key
  13. Enter your YubiKey PIN, then click OK. If you need help finding your PIN, please refer to this how-to.
    Enter PIN
  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.
    CSR file

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.
    Open PowerShell as administrator
  2. Use the following command to navigate to the YubiKey Manager files:
    • Windows:
      cd "C:Program FilesYubicoYubiKey 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.
    Attestation Certificate
  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.
    details
  3. Click the manage link, under attestation.
    manage link
  4. A new page with fields for the attestation and intermediate certificates will appear.
    Attestation Verification
  5. Paste the attestation certificate into the Attestation Certificate field, making sure to include the lines -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----.
    paste attestation certificate
  6. Next, paste the intermediate certificate into the Intermediate Certificate field.
    Intermediate Certificate field
  7. Click the Submit button.
    Submit button
  8. If everything has gone correctly, a green alert will appear at the top of the screen, indicating a successful attestation.
    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.
    Delete link
  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).

Warning: We have seen error messages in recent versions of YubiKey Manager when importing ECC certificates (now required for EV Code Signing on YubiKey). There are two potential workarounds:

  • Recommended: Convert the certificate to DER format before importing. This is a straightforward conversion with OpenSSL (replace CERT.crt and CERT.der with your actual filename in the following command):
    openssl x509 -outform der -in CERT.crt -out CERT.der
  • If you cannot convert your file, reverting to an earlier release of YubiKey Manager will also work. The most recent version we have found to successfully import ECC .crt files downloaded from SSL.com is 1.1.5.

Step 4: Install Certificate in YubiKey

  1. Launch YubiKey Manager and mavigate to Applications > PIV.
    Applications > PIV
  2. Click the Configure Certificates button.
    Configure Certificates
  3. Select the tab for the same YubiKey slot where you generated the key pair.
    Authentication (slot 9a)
  4. Click the Import button.
    Import button
  5. Navigate to your end-entity certificate file and click the Import button.
    import certificate
  6. Enter your YubiKey’s management key, then click OK. If you need your management key, please contact Support@SSL.com.
    management key
  7. The new EV code signing certificate is installed in the YubiKey.
    Certificate is installed
  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.
Thank you for choosing SSL.com! If you have any questions, please contact us by email at Support@SSL.com, call 1-877-SSL-SECURE, or just click the chat link at the bottom right of this page. You can also find answers to many common support questions in our knowledgebase.

Subscribe To SSL.com’s Newsletter

Don’t miss new articles and updates from SSL.com

Stay Informed and Secure

SSL.com is a global leader in cybersecurity, PKI and digital certificates. Sign up to receive the latest industry news, tips, and product announcements from SSL.com.

We’d love your feedback

Take our survey and let us know your thoughts on your recent purchase.