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.

Note: 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 purchased independently.

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

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

If you have not done so already, download and install YubiKey Manager from Yubico's website. Versions for Windows, Linux, and macOS are available.
Plug in your YubiKey, then launch YubiKey Manager. Your YubiKey should be displayed in the YubiKey Manager window.
Navigate to Applications > PIV.
Click the Configure Certificates button.
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.
Click the Generate button.
Select Certificate Signing Request (CSR), then click the Next button.
Select an Algorithm from the drop-down menu. For document signing, choose RSA2048. For EV code signing, choose ECCP256 or ECCP384.
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.
Click the Generate button.
Select a location to save the CSR file, create a filename, then click the Save button.
Enter your YubiKey's management key, then click OK. If you need your management key and it was ordered through us, please contact Support@SSL.com.
Enter your YubiKey PIN, then click OK. If you need help finding your PIN, please refer to this how-to.
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.

In Windows, open PowerShell as an administrator. macOS and Linux users should open a terminal window on their device.
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.
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
```
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

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.
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.
Click the manage link, under attestation.
A new page with fields for the attestation and intermediate certificates will appear.
Paste the attestation certificate into the Attestation Certificate field, making sure to include the lines -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----.
Next, paste the intermediate certificate into the Intermediate Certificate field.
Click the Submit button.
If everything has gone correctly, a green alert will appear at the top of the screen, indicating a successful attestation.
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.
After SSL.com processes your order, the certificate will be available in your SSL.com account.
Choose the individual certificates format when downloading.
Expand the zip file. There should be three certificate files: your end-entity certificate, an intermediate certificate, and a root certificate.

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

Launch YubiKey Manager and mavigate to Applications > PIV.
Click the Configure Certificates button.
Select the tab for the same YubiKey slot where you generated the key pair.
Click the Import button.
Navigate to your end-entity certificate file and click the Import button.
Enter your YubiKey's management key, then click OK. If you need your management key, please contact Support@SSL.com.
The new EV code signing certificate is installed in the YubiKey.
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.