Knowledge Base

Knowledge BaseCode Signing

How to Obtain an Attestation File and CSR from Google Cloud HSM

Updated on January 2, 2025

Prerequisites

Before starting, ensure the following:

Google Cloud Project: You must have a Google Cloud project with HSM set up.

Permissions: Ensure you have Cloud HSM Admin and Cloud KMS CryptoKey Encrypter/Decrypter roles.

gcloud CLI: Install the Google Cloud CLI on your system.

OpenSSL: Install OpenSSL for creating the CSR if needed.

Step 1: Set Up Your Environment

Login to Google Cloud:

gcloud auth login

2. Set your project:

gcloud config set project [PROJECT_ID]

Replace [PROJECT_ID] with your Google Cloud project ID.

3. Enable APIs: Ensure that the Cloud KMS API is enabled:

gcloud services enable cloudkms.googleapis.com

Step 2: Create a Key Ring and CryptoKey

1. Create a Key Ring:

gcloud kms keyrings create [KEY_RING_NAME] --location [LOCATION]

Replace [KEY_RING_NAME] with a name for your key ring and [LOCATION] with the desired location

(e.g., us-central1).

2. Create a CryptoKey:

gcloud kms keys create [KEY_NAME] \

--keyring [KEY_RING_NAME] \

--location [LOCATION] \

--purpose asymmetric-signing \

--default-algorithm rsa-sign-pkcs1-2048-sha256 \

--protection-level hsm

Replace [KEY_NAME] with the name of your key.

Step 3: Obtain the Attestation File

Export the attestation file (Google Cloud Console preferred):

Navigate to the Key Management page in Google Cloud Console.
Select the key ring and key.
For the desired key version, click on "More" (three dots) and select "Verify attestation."
In the dialog, click "Download attestation bundle" to obtain a ZIP file containing the attestation and certificate chains.

2. Alternative CLI Method:

gcloud kms keys versions describe [KEY_VERSION] \

--key [KEY_NAME] \

--keyring [KEY_RING_NAME] \

--location [LOCATION] \

--format 'value(attestation.format,attestation.content)' > attestation.txt

Replace [KEY_VERSION] with the version of the key (e.g., 1 ).

This command saves the attestation file in Base64 format. Decode it if needed:

cat attestation.txt | base64 --decode > attestation.bin

Note: The attestation file proves the key resides in a hardware security module.

Step 4: Generate a CSR

1. Use a Simplified Tool for CSR Generation (Recommended):

Use an open-source tool tailored for Google Cloud HSM to generate a CSR. Tools like mattes's CSR utility are available on platforms like GitHub and simplify the process.

2. Manual Configuration File Method: Create a file named csr_config.txt with the following content:

[ req ]

distinguished_name = req_distinguished_name

prompt = no

[req_distinguished name]

C = [COUNTRY]

ST = [STATE]

L = [CITY]

O = [ORGANIZATION]

OU = [ORGANIZATIONAL_UNIT]

CN = [COMMON_NAME]

Replace the placeholders (e.g., [COUNTRY], [STATE], etc.) with your information.

3. Generate the CSR:

gcloud kms keys versions describe [KEY_VERSION] \

--key [KEY_NAME] \

--keyring [KEY_RING_NAME] \

--location [LOCATION] \

--format 'value(attestation.certificate)' | base64 --decode > public_cert.pem

openssl req -new -key public_cert.pem -out request.csr -config csr_config.txt

This command generates the CSR file request.csr.

Step 5: Submit Files to the Certificate Authority

Provide the CSR and Attestation File: Submit the following files to your chosen Certificate Authority:

request.csr
attestation.bin

Follow CA Instructions:

Complete the CA's submission process.
Some CAs may charge a fee for attestation services.
Wait for the CA to issue your code-signing certificate.

Troubleshooting

Permission Errors: Verify your IAM roles and ensure the necessary APIs are enabled.
Invalid Attestation: Ensure the attestation file is correctly exported and decoded.
CSR Issues: Confirm that your CSR configuration file is accurate and matches the required format.
Verification of Attestation: Verify the attestation through the Google Cloud Console by selecting "Verify attestation" for the key version.