Verifying attestations  |  Cloud KMS Documentation  |  Google Cloud (2024)

This topic shows you how to verify attestations forCloud HSM keys, which are always stored in a hardwaresecurity module (HSM).

Overview

In cryptography, an attestation 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.

The attestation 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

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

• Download and install the script 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 bundleand attestation 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 the Key Management page in the Google Cloud console.

   Go to the Key Management page
   

   See Also

   Qu’est-ce que « com.wssyncmldm » dans Android ? - Pouvez-vous le supprimer ?What Is Com.wssyncmldm? And How To Disable It? | Yoodleycom wssyncmldm: what is it and how can I fix it? - DigitalTalkBlogThe Secrets Of Com.wssyncmldm On Samsung Android Devices

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

3. Click More more_vertfor the key version you want to attest, and select Verify attestation.

4. In the Verify attestation dialog, click Open 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 the attestation 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 the Key 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. Click More more_vertfor the key version you want to attest, and select Verify attestation.

   4. In the Verify attestation dialog, click Download Attestation Bundle.This will download a zip file containing the attestation andcertificate chains.

      See Also

      What is "com.wssyncmldm" in Android? - Can You Remove It?

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

   gcloud

   1. Click Activate 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 the gcloud 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 describe key-version \ --key key-name \ --location location \ --keyring keyring-name \ --attestation-file [attestation-file] \

   3. At the Cloud Shell command-line prompt, use the gcloud 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-chain key-version \ --key key-name \ --location location \ --keyring keyring-name \ --output-file [certificates-file] \

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

Parsing the attestation's values

The HSM 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 the 0x0102field 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 to get the key version resource ID oryou can run the following command:

   gcloud kms keys versions list \ --location location \ --keyring key-ring-name \ --key key-name

2. At the command line, assign resource_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 the KEYID_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 of RESOURCE_NAME_HEX and KEYID_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 the PKCS #11 standard. Use the followingexamples as guides to verify other properties of the key.

• Whether a key is extractable is stored in the 0x0102 field of the parsedoutput. To determine whether a key is extractable, examine the 0x0162 field.A value of \x01 is true and a value of \x00 is false.

  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 the 0x0163 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 the 0x0100 field. Key types are documented inthe PCKS#11 standard with prefix CKK_*. 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.