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.
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 or individual name 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. (Optional) Enter your YubiKey's management key, or check Use Default, and click OK.
Default Key: 010203040506070801020304050607080102030405060708
10. (Optional) Enter your YubiKey PIN and click OK.
Default PIN: 123456
Every YubiKey is equipped with a pre-loaded private key and certificate provided by Yubico. This enables you to generate an attestation certificate, which serves to validate that a private key has indeed been generated on a YubiKey. To perform this operation, you will need to utilize the command line interface using PowerShell.
1. Open a Power Shell Window as Administrator. Disclaimer: Our support team is unable to troubleshoot errors in Windows PowerShell.
2. Change directory to YubiKey directory:
cd 'C:\Program Files\Yubico\YubiKey Manager\'
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 and file name you want to use. For example, "C:\Documents\attestation.crt"
- If you used slot 9c, replace 9a with 9c
.\ykman.exe piv keys attest 9a ATTESTATION-FILENAME.crt
/ykman piv keys attest 9a ATTESTATION-FILENAME.crt
ykman piv keys attest 9a ATTESTATION-FILENAME.crt
4. To proceed, utilize the ykman command to export the intermediate certificate from slot f9 of the YubiKey. Again, make sure to replace INTERMEDIATE-FILENAME.crt with the full directory path and filename you want to use.
.\ykman.exe piv certificates export f9 INTERMEDIATE-FILENAME.crt
./ykman piv certificates export f9 INTERMEDIATE-FILENAME.crt
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.