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.
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 and click OK.
Default Key: 010203040506070801020304050607080102030405060708
10. (Optional) Enter your YubiKey PIN and click OK.
Default PIN: 123456
Generate Attestation
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:
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 (change the path where to save the attestation certificate):
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. To proceed, utilize the ykman command to export the intermediate certificate from slot f9 of the YubiKey. Make sure to replace INTERMEDIATE-FILENAME.crt with your desired path and filename.
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. Now please merge both attestation and intermediate certificates using text editor in the same order and save that as single file and upload that during certificate generation process.
