This guide shows you how to verify attestations forCloud HSMkeys, which are always stored in a hardware security module(HSM). This guide applies to both Multi-tenant Cloud HSM andSingle-tenant Cloud HSM keys.

Overview

In cryptography, anattestation is a machine-readable, programmaticallyprovable statement that a piece of software makes about itself. Attestations arean important component of trusted computing, and may be required for compliancereasons.

To view and verify the attestations, you request a cryptographically-signedattestation statement from the HSM, along with the certificate chains usedto sign it. The attestation statement is produced by the HSM hardware, andsigned by certificates owned by Google and by the HSM manufacturer.

After downloading the attestation statement and the certificate chains, you cancheck its attributes orverify the validity of the attestation using thecertificate chains.

Theattestation script is an open sourcePython script developed by Google. You can view the source code for the scriptto learn more about the attestation format and how verification works, oras a model for a customized solution.

The examples in this topic are designed for Linux environments, including theCloud Shell. To follow along on macOS or Windows clients, you mayneed to make modifications.

Before you begin

• If necessary,create a Cloud HSM key on a key ring in aregion supported by Cloud HSM.

• Download and install thescripts for parsing the attestation's values.from the HSM manufacturer. Download each of these scripts:

  • verify_pubkey.py
  • parse_v1.py
  • parse_v2.py
  Note: Do not downloadverify_attest.py. Instead, use theverification script provided by Google.

  Look over the documentation for using the scripts, provided at the samelocation.

• Download and install thescript for verifying attestations and its prerequisites, and look over the documentation for the script.

Verifying the attestation

The attestation verification process can either be performed automaticallythrough the Google Cloud console, or manually by downloading the attestation bundleandattestation verification script andrunning it locally or in the Cloud Shell.

Verifying attestations through the Google Cloud console

You can verify the attestation through the Google Cloud console, which willopen a Cloud Shell and pre-populate it with the code snippets needed toperform the entire attestation verification process.

1. Go to theKey Management page in the Google Cloud console.

   Go to the Key Management page
   

2. Select the key ring that contains the key you want to attest, then selectthe key.

3. ClickMoremore_vertfor the key version you want to attest, and selectVerify attestation.

4. In theVerify attestation dialog, clickOpen Cloud Shell. Thiswill open the Cloud Shell and pre-populate it with the code snippetneeded to go through the entire verification process.

5. Inspect the pre-populated code snippet in the Cloud Shell. Thesnippet downloads theattestation verification script and its dependencies, runs the gcloud commands to download the attestationand certificate chains, and then runs the script to verify the attestation.

6. Run the code snippet to verify the attestation.

Verifying the attestation manually

The attestation, certificate chains, and attestation verification script need tobe downloaded before manually verifying the attestation.

1. Download the attestation and certificate chains.

   Console

   1. Go to theKey Management page in the Google Cloud console.

      Go to the Key Management page
      

   2. Select the key ring that contains the key you want to attest, then selectthe key.

   3. ClickMoremore_vertfor the key version you want to attest, and selectVerify attestation.

   4. In theVerify attestation dialog, clickDownload Attestation Bundle.This will download a zip file containing the attestation andcertificate chains.

   5. Extract the attestation and certificate chains from the attestationbundle.

   gcloud

   1. ClickActivate Cloud Shell at the top ofthe console window.

      A Cloud Shell session opens inside a new frame at the bottom ofthe console and displays a command-line prompt. It can take a fewseconds for the shell session to be initialized.

      

   2. At the Cloud Shell command-line prompt, use thegcloud kmskeys versions describe command to retrieve the attestation for thekey that you want to attest. The--attestation-file flag specifiesthe path and filename destination for the retrieved attestation.

      gcloud kms keys versions describekey-version \ --keykey-name \ --locationlocation \ --keyringkeyring-name \ --attestation-file[attestation-file] \

   3. At the Cloud Shell command-line prompt, use thegcloud kmskeys versions get-certificate-chain command to retrieve thecertificate chains for the key that you want to attest. The--output-file flag specifies the path and filename destination forthe retrieved certificates.

      gcloud kms keys versions get-certificate-chainkey-version \ --keykey-name \ --locationlocation \ --keyringkeyring-name \ --output-file[certificates-file] \

2. Download thescript for verifying attestations and its prerequisites, and go through thedocumentation for the script to verify the attestation in the attestation file using the certificates inthe certificates file.

Parsing the attestation's values

TheHSM manufacturer's documentation includes full instructions for using their scripts to parse an attestation'svalues and verify the public key for an asymmetric key pair. The attestationwill need to be decompressed with the following command before it can beparsed.

• Uncompress the compressed attestation.

  gzip -d <compressed_attestation.dat >attestation.dat

These links go directly to specific instructions from the HSM manufacturer:

• Verify an asymmetric keypair's public key
• Parse the attestation's values

The instructions for parsing the attestation's value include a reference ofgeneral fields in the attestation, not specific to HSM keys in Cloud HSM.

The following sections illustrate how to verify information about your keys thatis specific to Cloud HSM.

Verify the key's version ID

You can verify whether the SHA-256 hash of the key version resource ID ispresent in the attestation. The key's resource name is part of the0x0102field or key ID field in the attestation file. The key ID is composed of twoconcatenated SHA-256 hash digests in hex format. The second one should matchthe key's resource name.

1. Get the key version resource ID for the key version. You can use theGoogle Cloud console toget the key version resource ID oryou can run the following command:

   gcloud kms keys versions list \   --locationlocation \   --keyringkey-ring-name \   --keykey-name

2. At the command line, assignresource_name to the key version resource IDthat you just retrieved.

   RESOURCE_NAME="projects/project-id/locations/location/keyRings/key-ring-name/cryptoKeys/key-name/cryptoKeyVersions/key-version"

3. Since the parse script dumps all attestation fields in hex format, the keyID would have been formatted into hex format twice. (Once while creating thekeyID, the other while parsing the attestation). To verify that the resourcename matches with the key ID, convert the resource name to a SHA-256 hex digest,revert one hex conversion of the key ID in the attestation file, and comparethe two.

   RESOURCE_NAME_HEX="$(echo -n ${RESOURCE_NAME} | openssl dgst -sha256 -hex | awk '{print $2}')"

4. The parse script dumps all attestation fields in hex format, and the key IDis internally hex-encoded a second time. Set theKEYID_HEX environmentvariable to the value of the key ID with one layer of hex-encoding decoded:

   KEYID_HEX=$(grep -m 1 0x0102/path/to/parsed/attestation.dat | awk '{print $2}' | xxd -p -r)

5. Compare the values ofRESOURCE_NAME_HEX andKEYID_HEX as strings:

   test  ${RESOURCE_NAME_HEX} == ${KEYID_HEX:(-64)} || echo "Values don't match"

   If the values match, no output is returned and the command exits with code0.

Verify other properties of the key

You can view various key properties, which correspond tofields in thePKCS #11 standard. Use the followingexamples as guides to verify other properties of the key.

• Whether a key is extractable is stored in the0x0102 field of the parsedoutput. To determine whether a key is extractable, examine the0x0162 field.A value of\x01 istrue and a value of\x00 isfalse.

  Cloud HSM keys are not extractable.

  grep '0x0162:'/path/to/parsed/attestation.dat

• How the key got into the HSM (whether it was created directly orimported) is stored in the0x0163 field. Ifthe key was created locally on the HSM, the field is set to\x01. Animported key's field is set to\x00.

  You can infer a few pieces of information from how the key came to be on theHSM. If the key was created in Cloud HSM, that means the key hasnever been stored unencrypted outside of an HSM. If the key was imported, thenthe import mechanism guarantees that the key is protected at transit during theimport process, and within Cloud HSM afterward.

  grep '0x0163:'/path/to/parsed/attestation.dat

• A key's type is stored in the0x0100 field. Key types are documented inthe PCKS#11 standard with prefixCKK_*. For example, an AES key has a type of\x1f.

  grep '0x0100:'/path/to/parsed/attestation.dat

Additional information

You verify an attestation to determine whether a key version was createdinside an HSM.