These instructions cover the full process for code signing with Google Cloud Key Management services, including:

  • Create the key and attestation
  • Create the certificate signing request
  • Complete certificate enrollment
  • Sign code with SignTool

Before you begin, you must have purchased a code signing certificate using the "Install on Existing HSM" certificate delivery method. 

This guide references Google Cloud and Github documentation. For instructions on signing with other tools please refer to Google Cloud documentation for the specific tool. 

Create the key & attestation

 First, you’ll need to generate a key pair in Google Cloud. Complete these steps in the Google Cloud dashboard/console: 

  1. In Google KMS, create a key ring 
  2. Create a new keywith these settings:
    1. HSM protection 
    2. HSM-generated 
    3. Asymmetric signing 
    4. If you're not sure what key type/size your signing tool requires, we suggest using 4096-bit RSA, PKCS#1 v1.5 padding - SHA256 Digest (this is compatible with Microsoft CNG API and many tools). 
  3. Open the page for the newly-created key, click the Actions dropdown next to the key version, click Verify attestation, then click Download Attestation Bundle and download the zip file (you’ll need this later)

Create the CSR

Next, you’ll need to generate a CSR using the key you just generated. There are several different ways you can generate the CSR, in this tutorial we’ll walk you through doing it with OpenSSL on Linux (Ubuntu). 

  1. Setup a Linux computer/server with OpenSSL installed 
  2. Install the libengine-pkcs11-openssl package: sudo apt-get install libengine-pkcs11-openssl 
  3. Download the Google PKCS #11 library and extract it. You don’t need to run any install command—you’ll reference the file location directly in the next step 
  4. Configure OpenSSL to use the Google PKCS library with this command: export PKCS11_MODULE_PATH="/path/to/libkmsp11.so" (modify the path to reflect the location where you extracted the library)) 
  5. Create a YAML config file and set the KMS_PKCS11_CONFIG environment variable to point to it as described in Google PKCS #11 library configuration 
    1. You can get the key_ring value by going to Google Cloud Console - Key Rings
  6. Setup an authentication method for Google KMS using Workload Identity Federation or create a Service Account. To create a service account, follow these steps: 
    1. Go to Google Console Service Accounts and open up the applicable project 
    2. Click Create Service Account 
    3. Grant both Cloud KMS Admin and Cloud KMS Crypto Operator roles to the service account. This is needed to include all of the permissions listed at Github - Authentication and Authorization
    4. After creating the service account, create a new JSON key
    5. Download the key file and place it on the computer/server you’re using to create the CSR 
  7. Set the environment variable to point to your key file, eg. run: export GOOGLE_APPLICATION_CREDENTIALS="/root/gckms_auth.json" (Update the path to where you’ve stored the file.) 
  8. You’ve now configured OpenSSL to use Google KMS as a PKCS #11 provider. If you need to troubleshoot your connection to Google KMS: 
    1. Install the pkcs11-tool with sudo apt install opensc 
    2. Run pkcs11-tool --module /path/to/libkmsp11.so --list-objects to see the list of keys you can access. (Update the path to where you’ve stored the file.) 
  9. 12. You can now generate the CSR using a command like this: openssl req -new -subj '/CN=Your Company Name, LLC/' -sha256 -engine pkcs11 -keyform engine -key pkcs11:object=your_key_name > code_signing_request.csr 
  10. a. your_key_name is the key name in Google KMS, for example “mycskey” (NOT the entire resource name such as “projects/project-name/locations/us-east1/keyRings/ring-name/cryptoKeys/keyname/cryptoKeyVersions/1”) 
  11. b. It is possible to use id=entire_resource_name, but there is a 100 character limit so that is prone to errors; see Github Issue #531
  12. c. Be sure that the digest algorithm (-sha256 in the above example) matches what you chose when generating the key.

Submit the CSR and complete enrollment

Complete the certificate enrollment/generation process with your certificate provider, submitting the CSR and key attestation when prompted. 

Important: The key attestation file must be a zip file. Google Cloud offers two different places/formats where you can download an attestation file, be sure you get the .zip version. 

Sign code 

After your code signing certificate has been issued, you will be able to use it to sign executables. Here are instructions for signing with SignTool on a Windows machine: 

  1. Ensure that you have SignTool installed on your computer. 
  2. Install the latest Google Cloud KMS CNG provider release on your Windows machine using the .msi installer. 
  3. Run gcloud auth application-default login to authenticate your machine into Google Cloud 
  4. You’ll now be able to sign your executable using SignTool

Example command: 

signtool sign /v /debug /fd sha256 /t http://timestamp.sectigo.com /f path/to/mycertificate.crt /csp "Google Cloud KMS Provider" /kc projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME/cryptoKeyVersions/1 path/to/file.exe

(Update the path to where you’ve stored the certificate file.)