This guide includes instructions for completing your code signing order using the Install on Existing HSM method, specifically for the YubiKey 5 FIPS Series. The instructions provided are for Windows only, other operating systems should refer back to Yubico for more information.
This guide also assumes you already own your YubiKey HSM device and are familiar with the
associated software. You must own this hardware prior to placing your code signing order. If you
are less familiar with hardware security modules, you may wish to instead order a pre-configured
certificate token (Token + Shipping method).
The instructions below are provided by Sectigo CA. Please refer back to the specific
manufacturer of your hardware security module (HSM) for further instructions, as we cannot
provide support for third-party hardware.
YubiKey HSM Attestation Package
YubiKey 5 FIPS Series USB tokens can generate attestation certificates. An attestation certificate will have the same key as the CSR and is signed by the intermediate certificate (this certificate can be downloaded from the HSM). The intermediate certificate in turn is signed by the YubiKey private root certificate.
Note: Please refer to PIV: FIPS 140-2 with YubiKey 5 FIPS Series — YubiKey 5 FIPS Series Technical Manual documentation (yubico.com) for more technical documentation on YubiKey 5 FIPS Series.
Attestation Package Format
This service expects a Base64-encoded PEM certificate chain containing two certificates:
- Attestation certificate that matches given CSR.
- Intermediate certificate.
Generate CSR
To generate a CSR and attestation certificate for the CSR and get an intermediate attestation certificate from the device:
Note: These instructions are for Windows. If you have a different operating system, see YubiCo for instructions.
1. Plugin your YubiKey 5 FIPS HSM and launch YubiKey Manager. Your YubiKey 5 FIPS device should be displayed in the Manager window.
2. Navigate to Applications > PIV and click Configure Certificates.
3. Select Authentication (Slot 9a) (for EV code signing certificates) and click Generate.
4. Select Certificate Signing Request (CSR) and click Next.
5. Select an algorithm from the drop-down menu and click Next.
Note: Select ECCP256 or ECCP384 for EV Code Signing Certificates as YubiKey supports only ECC algorithms for EV Code Signing. Please do not select RSA2048.
6. Enter a Subject Name for the certificate and click Next. In the example below the subject
name is set as Sectigo, but please make sure to use the name of your own organization here.
7. Confirm the details shown and click Generate.
8. Select a directory and enter a recognizable file name to save the CSR so you may locate it
later.
9. Enter your YubiKey’s management key OR click “Use default” and click OK. Default Key: 010203040506070801020304050607080102030405060708
10. Enter your YubiKey PIN and click OK.Default PIN: 123456
Generate Attestation
You will use a command line interface such as Windows PowerShell or MacOS Terminal to generate the attestation file.
1. Change the directory to the YubiKey directory.
Windows
cd 'C:\Program Files\Yubico\YubiKey Manager\'
MacOS
cd/Applications/Yubikey/Manager.app/Contents/MacOS
Linux (Ubuntu), the ykman command should already be installed in your PATH, so there is no need to perform this step.
3. Execute the following command to create the attestation certificate.
Keep in mind:
- Replace “ATTESTATION-FILENAME.crt” with the full directory path and filename you want to use. For example, “C:\Documents\attestation.crt”
- If you used slot 9c, put 9c instead of 9a
Windows:
.\ykman.exe piv keys attest 9a ATTESTATION-FILENAME.crt
MacOS:
/ykman piv keys attest 9a ATTESTATION-FILENAME.crt
Linux (Ubuntu):
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 (again, replace INTERMEDIATE-FILENAME.crt with the full directory path and filename you want to use):
Windows:
.\ykman.exe piv certificates export f9 INTERMEDIATE-FILENAME.crt
MacOS:
./ykman piv certificates export f9 INTERMEDIATE-FILENAME.crt
Linux (Ubuntu):
ykman piv certificates export f9 INTERMEDIATE-FILENAME.crt
5. Merge the attestation and intermediate files into one using a text editor such as Notepad. You can open the .crt files in a text editor and copy/paste the full text. The attestation CSR should be first, followed by the intermediate.
Save this text file and upload on your certificate order form to complete enrollment.
Possible Errors
ErroCode:-129 <br/>ErrorMessage:service response: invalid attestation chain: expecting 2 certificates but got 1.
This error can occur if your attestation bundle does not include the intermediate file. Make sure your attestation bundle includes the attestation certificate followed by the intermediate certificate, in that order.
ErroCode:-129 <br/>ErrorMessage:service response: failed to verify that csr public key matches public key in the attestation certificate.
This error can occur if the attestation certificate does not match the CSR submitted on the order form. You may have submitted a different CSR file than the one that generated the attestation. In this case, you may need to start over from the CSR generation step and create a new attestation package.
This error can also occur if the Intermediate certificate file is ordered first in the attestation bundle, or if the bundle contains only the Intermediate with no attestation certificate. Make sure your bundle includes the attestation certificate followed by the intermediate certificate as in the example above.
ErroCode:-129 <br/>ErrorMessage:service response: failed to parse attestation as a valid pem certificate chain.
This error can occur if the correct attestation certificate is not included in the bundle file. Please make sure you do not use the CSR file generated in YubiKey manager in place of the attestation certificate. You must generate the attestation certificate in your command line interface.
ErroCode-129 <br/>ErrorMessage service response failed to confirm that device is fips certified
This error means your YubiKey HSM device is not FIPS-compliant and cannot be used for code signing. You need a device from the YubiKey 5 FIPS series to install code signing certificates. If your device does not include FIPS in the model name, it will not work. You can confirm the model name of your YubiKey device on the home page of YubiKey manager.
Find YubiKey 5 FIPS compliant devices on YubiKey’s website.