Verifying attestations

This topic shows you how to verify attestations for Cloud HSM keys, which are always stored in a hardware security module (HSM).

Overview

In cryptography, an attestation is a machine-readable, programmatically provable statement that a piece of software makes about itself. Attestations are an important component of trusted computing, and may be required for compliance reasons.

To view and verify the attestations, you request a cryptographically-signed attestation statement from the HSM, along with the bundle of certificates used to sign it. The attestation statement is produced by the HSM hardware, and signed by certificates owned by Google and by the HSM manufacturer.

After downloading the attestation statement and the certificates, you verify the validity of the certificates in the bundle, then verify the attestation statement itself.

The attestation statement's format is defined by the HSM manufacturer. It's not possible to verify an attestation using the Cloud Console, the Cloud KMS API, or the gcloud tool. The verification is intentionally independent of Google.

The attestation script is an open source Python script developed by Google. You can view the source code for the script to learn more about the attestation format and how verification works, or as a model for a customized solution.

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

Before you begin

If necessary, create a Cloud HSM key on a key ring in a region supported by Cloud HSM.
Download and install the scripts 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 download verify_attest.py. Instead, use the verification script provided by Google.

Look over the documentation for using the scripts, provided at the same location.
Download and install the script for verifying attestations and its prerequisites, and look over the documentation for the script.

Downloading the artifacts

Before you attest a key, you download the certificates and the attestation statement.

Downloading the certificates

The signature of an attestation can be verified using a certificate bundle leading up to the root certificates for Google and the HSM manufacturer, and signed by the certificate authorities (CAs) for both Google and the HSM manufacturer.

Download the certificate bundle that leads up Google's root certificate.

curl -O https://www.gstatic.com/cloudhsm/cloud-kms-prod-[location]-google.pem

Download the certificate bundle that leads up to the HSM manufacturer's root certificate.
```
curl -O https://www.gstatic.com/cloudhsm/cloud-kms-prod-[location]-cavium.pem
```

Download Google's root certificate.

curl -O https://www.gstatic.com/cloudhsm/roots/global_1498867200.pem

Download and extract the HSM manufacturer's root certificate and public key.
```
curl -O https://www.marvell.com/content/dam/marvell/en/public-collateral/security-solutions/liquid_security_certificate.zip

unzip liquid_security_certificate.zip
```
The certificate is extracted to liquid_security_certificate.crt and the public key is extracted to liquid_security_certificate.txt.

Downloading the attestation statement

You can download the attestation for a cryptographic key version using the Google Cloud Console or the command line. The attestation statement is downloaded directly from the HSM device that contains the key.

Console

Go to the Cryptographic Keys page in the Cloud Console.

Go to the Cryptographic Keys page
Select the key ring that contains the key you want to attest, then select the key.
Click the More icon (3 vertical dots) for the key version you want to attest, and select Get attestation.
In the Get attestation dialog, click Download. The attestation file is downloaded to your local system.

The format for the name of the attestation file is [keyring-name]-[key-name]-[key-version]-[attestation-format]-attestation.dat. Each portion of the file name is separated by a hyphen. For that reason, placeholder text is surrounded by square bracket ([ and ]) characters.

gcloud

Click Activate Cloud Shell at the top of the console window.

A Cloud Shell session opens inside a new frame at the bottom of the console and displays a command-line prompt. It can take a few seconds for the shell session to be initialized.
At the Cloud Shell command-line prompt, use the gcloud kms keys versions describe command to retrieve the attestation format for the key that you want to attest.
```
gcloud kms keys versions describe key-version \
  --key key-name \
  --location location \
  --keyring keyring-name
```
The output from this command shows the key version's attestation format, which you will need for the next step.
At the Cloud Shell command-line prompt, use the gcloud kms keys versions describe command to retrieve the attestation for the key that you want to attest, replacing attestation-format with the attestation format that you retrieved in the previous step. The --attestation-file flag specifies the path and filename destination for the retrieved attestation. Each portion of the file name is separated by a hyphen. For that reason, placeholder text is surrounded by square bracket ([ and ]) characters.
```
gcloud kms keys versions describe key-version \
 --key key-name \
 --location location \
 --keyring keyring-name \
 --attestation-file \
 [keyring-name]-[key-name]-[key-version]-[attestation-format]-attestation.dat
```

Verifying the attestation's signature

To verify an attestation's cryptographic signature, you can use an open source script.

You can also verify the public key for an asymmetric key pair.

Parsing the attestation's values

The HSM manufacturer's documentation includes full instructions for using their scripts to parse an attestation's values and verify the public key for an asymmetric key pair. These links go directly to specific instructions from the HSM manufacturer:

The instructions for parsing the attestation's value include a reference of general fields in the attestation, not specific to HSM keys in Cloud HSM. The following sections illustrate how to verify information about your keys that is specific to Cloud HSM, such as the version ID.

The following sections provide instructions for verifying specific pieces of metadata about a Cloud HSM key.

Verify the key's version ID

You can verify whether the SHA-256 hash of the key version resource ID is present in the attestation. The key's resource name is part of the 0x0102 field or key ID field in the attestation file. The key ID is composed of two concatenated SHA-256 hash digests in hex format. The second one should match the key's resource name.

Get the key version resource ID for the key version. You can use the Cloud Console to get the key version resource ID or you can run the following command:
```
gcloud kms keys versions list \
   --location location \
   --keyring key-ring-name \
   --key key-name
```

At the command line, assign resource_name to the key version resource ID that you just retrieved.

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

Since the parse script dumps all attestation fields in hex format, the key ID would have been formatted into hex format twice. (Once while creating the keyID, the other while parsing the attestation). To verify that the resource name 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 compare the two.
```
RESOURCE_NAME_HEX="$(echo -n ${RESOURCE_NAME} | openssl dgst -sha256 -hex | awk '{print $2}')"
```
The parse script dumps all attestation fields in hex format, and the key ID is internally hex-encoded a second time. Set the KEYID_HEX environment variable to the value of the key ID with one layer of hex-encoding decoded:
```
KEYID_HEX=$(grep -m 1 0x0102 /path/to/attestation.dat | awk '{print $2}' | xxd -p -r)
```
Compare the values of RESOURCE_NAME_HEX and KEYID_HEX as strings:
```
test  ${RESOURCE_NAME_HEX} == ${KEYID_HEX} || echo "Values don't match"
```
If the values match, no output is returned and the command exits with code 0.

Verify other properties of the key

You can view various key properties, which correspond to fields in the PKCS #11 standard. Use the following examples as guides to verify other properties of the key.

Whether a key is extractable is stored in the 0x0102 field of the parsed output. 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/attestation.dat
```
How the key got into the HSM (whether it was created directly or imported) is stored in the 0x0163 field. If the key was created locally on the HSM, the field is set to \x01. An imported key's field is set to \x00.

You can infer a few pieces of information from how the key came to be on the HSM. If the key was created in Cloud HSM, that means the key has never been stored unencrypted outside of an HSM. If the key was imported, then the import mechanism guarantees that the key is protected at transit during the import process, and within Cloud HSM afterward.
```
grep '0x0163:' /path/to/attestation.dat
```
A key's type is stored in the 0x0100 field. Key types are documented in the PCKS#11 standard with prefix CKK_*. For example, an AES key has a type of \x1f.
```
grep '0x0100:' /path/to/attestation.dat
```

Additional information

You verify an attestation to determine whether a key version was created inside an HSM. Because the verification is intentionally independent of Google, you cannot verify an attestation using the Cloud Console, the Cloud KMS API, or the gcloud tool.