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
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 toliquid_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.
Select the key ring that contains the key you want to attest, then select the key.
Click More more_vert 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. The attestation will need to be decompressed with the following command before it can be parsed.
Uncompress the compressed attesation.
gzip -d < compressed_attestation.dat > attestation.dat
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.
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/parsed/attestation.dat | awk '{print $2}' | xxd -p -r)
Compare the values of
RESOURCE_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 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 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 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/parsed/attestation.dat
A key's type is stored in the
0x0100
field. Key types are documented in the 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 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.