Verifying attestations for Cloud HSM keys

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

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, 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 and the verification scripts are provided 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 format and the scripts used to parse and verify the attestation are provided and maintained by the HSM manufacturer.

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

Before you begin

  • OpenSSL must be installed on the client. If you use the Cloud Shell, OpenSSL is configured correctly.

  • Install the pyopenssl library. The following command is one way to install it, using pip: pip.

    pip install --user pyopenssl
    
  • Create Cloud HSM key on a key ring that is located in a region supported by Cloud HSM. Cloud HSM keys are not available in the global region.

  • Download the verify_attest.py, verify_pubkey.py, parse_v1.py, and parse_v2.py scripts from the HSM manufacturer. Familiarize yourself with the instructions for using the scripts, provided at the same location.

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.

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

    curl -O https://www.gstatic.com/cloudhsm/cloud-kms-prod-[location]-google.pem
    
  2. 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
    
  3. Download Google's root certificate.

    curl -O https://www.gstatic.com/cloudhsm/roots/global_1498867200.pem
    
  4. 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

  1. Go to the Cryptographic Keys page in the Cloud Console.

    Go to the Cryptographic Keys page

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

  3. Click the More icon (3 vertical dots) for the key version you want to attest, and select Get attestation.

  4. 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

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

    Activate Cloud Shell 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.

    Cloud Shell session

  2. 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.

  3. 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 and parsing the attestation

The HSM manufacturer's documentation includes full instructions for using their scripts to verify and parse an attestation. 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.

Verifying 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 in the attestation file. This field contains the key ID. The key ID is composed of two concatenated SHA-256 hash digests in hex format. The second hash digest should match the key's resource name.

  1. 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 keyring-name \
     --key key-name
    
  2. Set the RESOURCE_NAME environment variable to the key version resource ID that you just retrieved.

    RESOURCE_NAME="projects/project-id/locations/location/keyRings/keyring-name/cryptoKeys/key-name/cryptoKeyVersions/key-version""
    
  3. Set the RESOURCE_NAME_HEX environment variable to the hex-enoded value for the resource ID, since the value in the attestation statement is also hex-encoded.

    RESOURCE_NAME_NEX="$(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 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.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} || echo "Values don't match"
    

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

Verifying 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:' parsed.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:' parsed.dat
    
  • Whether a key was imported, rather than created in Cloud HSM, is stored in the 0x0163 field. A value of \x01 is true and a value of \x00 is false.

    grep '0x0163:' parsed.dat