Verifying attestations

For a key that is created in Cloud HSM, you can optionally request an attestation statement to provide evidence that the key is actually HSM-protected. The statement is a token that is cryptographically signed directly by the physical hardware and can be verified by the user. This topic describes how to verify the attestation statement signature and determine whether the attestation statement matches the key version.

The examples in this topic are for Linux environments.

Before you begin

This topic provides examples that use the command line. For simplicity, we'll use the Cloud Shell. The attestation example uses OpenSSL, which is pre-installed on Cloud Shell.
If you haven't already, create a key ring in one of the regions supported by Cloud HSM and create a key with protection level HSM.
Create the Python scripts shown below.

Script for verifying an attestation

To help you verify an attestation, at the command line where you are going to verify the attestation, create verify.py. If you are using the Cloud Shell, you can use the Code editor to create this file. Use the following contents for this file.

#!/usr/bin/env python
from OpenSSL import crypto
import gzip,sys

_END_DELIM = "-----END CERTIFICATE-----"
def verify(blob, signature, certs_file):
  with open(certs_file, 'r') as cert_data:
    certs = [cert + _END_DELIM for cert in cert_data.read().split(_END_DELIM)
             if cert.strip(' \t\n\r')]
    for cert in certs:
      cert_obj = crypto.load_certificate(crypto.FILETYPE_PEM, cert)
      try:
        crypto.verify(cert_obj, signature, blob, 'sha256')
        return True
      except crypto.Error as er:
        continue
    return False

attest_unzipped = gzip.open(sys.argv.pop(), 'rb').read()
certs_file = sys.argv.pop()
blob, signature = attest_unzipped[:-256], attest_unzipped[-256:]
verified = verify(blob, signature, certs_file)
print('Signature verified!' if verified else 'Signature failed!')

Script for parsing an attestation

There are two different scripts for parsing an attestation, because there are two attestation formats, CAVIUM_V1_COMPRESSED and CAVIUM_V2_COMPRESSED.

Script for parsing a CAVIUM_V1_COMPRESSED attestation

Create a file named parse_v1.py with the following contents.

#!/usr/bin/python
import io, gzip, sys, struct

HEADER = ">III"
TLV = ">II"
_CAVIUM_ATTESTATION_ASYM_OFFSET = 984
_CAVIUM_ATTESTATION_SYM_OFFSET = 24

def parse(attestation):
  # Parse Object (Cavium stores its structures in big endian)
  obj_handle, attr_count, obj_size = struct.unpack_from(HEADER, attestation, 0)
  obj_header_size = struct.calcsize(HEADER)
  attestation = attestation[obj_header_size:]
  while attr_count > 0:
    # Parse each Attribute.
    attr_type, attr_len = struct.unpack_from(TLV, attestation, 0)
    attestation = attestation[struct.calcsize(TLV):]
    print '0x%04x: %r' % (attr_type, attestation[:attr_len])
    attr_count -= 1
    attestation = attestation[attr_len:]
  return obj_header_size + obj_size

attest_unzipped = gzip.open(sys.argv.pop(), 'rb').read()
key_type = sys.argv.pop()
if key_type == 'symmetric':
  print "Symmetric Key Attestation"
  parse(attest_unzipped[_CAVIUM_ATTESTATION_SYM_OFFSET:])
else:
  print "Public Key Attestation"
  offset = parse(attest_unzipped[_CAVIUM_ATTESTATION_ASYM_OFFSET:])
  print 'Private Key Attestation'
  parse(attest_unzipped[(_CAVIUM_ATTESTATION_ASYM_OFFSET + offset):])

Script for parsing a CAVIUM_V2_COMPRESSED attestation

Create a file named parse_v2.py with the following contents.

#!/usr/bin/python
import io, gzip, sys, struct

RESPONSE_HEADER = ">IIII"
INFO_HEADER = ">HHHH"
OBJ_HEADER = ">III"
TLV = ">II"
SIGNATURE_SIZE = 256

def parse(attestation):
  # Parse Object
  obj_handle, attr_count, obj_size = struct.unpack_from(OBJ_HEADER, attestation, 0)
  obj_header_size = struct.calcsize(OBJ_HEADER)
  attestation = attestation[obj_header_size:]
  while attr_count > 0:
    # Parse each Attribute.
    attr_type, attr_len = struct.unpack_from(TLV, attestation, 0)
    attestation = attestation[struct.calcsize(TLV):]
    attr_val = "".join(['%02x' % ord(ch) for ch in attestation[:attr_len]])
    print '0x%04x: %r' % (attr_type, attr_val)
    attr_count -= 1
    attestation = attestation[attr_len:]
  return obj_header_size + obj_size

attest_unzipped = gzip.open(sys.argv.pop(), 'rb').read()

## Parse headers (Cavium stores its structures in big endian)
_, _, totalsize, bufsize = struct.unpack_from(RESPONSE_HEADER, attest_unzipped, 0)
attribute_offset = totalsize - (bufsize + SIGNATURE_SIZE)
attestation = attest_unzipped[attribute_offset:]
version, _, offset1, offset2 = struct.unpack_from(INFO_HEADER, attestation, 0)

if offset2 > 0:
  print "Public Key Attestation"
  parse(attestation[offset1:])
  print "Private Key Attestation"
  parse(attestation[offset2:])
else:
  print "Symmetric Key Attestation"
  parse(attestation[offset1:])

Script for verifying a public key

To help you verify a public key, create a file named verify_pubkey.py with the following contents.

#!/usr/bin/env python
import sys, base64, hashlib

public_key_file = sys.argv.pop()
parsed_attest_file = sys.argv.pop()
with open(public_key_file, 'r') as public_key_data:
  # remove the "BEGIN" and "END" line.
  publickey = "".join(public_key_data.read().split('\n')[1:-2])
  publickey = base64.b64decode(publickey)
  # KCV is the first 6 bytes of the SHA1 digest of the key.
  kcv = hashlib.sha1(publickey).hexdigest()[:6]
  # EKCV is the SHA256 digest of the key
  ekcv = hashlib.sha256(publickey).hexdigest()

  with open(parsed_attest_file, 'r') as parsed_attest_data:
    attest_data = parsed_attest_data.read()
    if ekcv in attest_data and ekcv in attest_data:
      print 'Public key matched with attestation.'
    else:
      print 'Public key not matched with attestation.'
      attest_lines = attest_data.split('\n')
      # field 0x0173 corresponds to KCV,
      # field 1003 (Custom Cavium) corresponds to EKCV
      kcv_lines = [line for line in attest_lines if line.startswith('0x0173:') or line.startswith('0x1003:')]
      print "KCV in attestation: %s" %(kcv_lines)

Retrieve the attestation file

You can retrieve the attestation for a cryptographic key version using the Google Cloud Console or the command line.

Console

Go to the Cryptographic Keys page in the Cloud Console.
Go to the Cryptographic Keys page
Click the name of the key ring that contains the key whose key version you want to attest.
Click the key whose key version you want to attest.
For the key version that you want to attest, click the More icon (3 vertical dots).
Click Get attestation.
In the Get attestation dialog, click Download. The attestation file is downloaded to your computer.

The format for the name of the attestation file is [KEYRING]-[KEY]-[KEYVERSION]-[ATTESTATION-FORMAT]-attestation.dat.

Command-line

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 [KEY_RING]
```
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.
```
gcloud kms keys versions describe [KEY_VERSION] \
  --key [KEY_NAME] \
  --location [LOCATION] \
  --keyring [KEY_RING] \
  --attestation-file \
  [KEYRING]-[KEY]-[KEYVERSION]-[ATTESTATION-FORMAT]-attestation.dat
```

Attest a key

The signature of an attestation can be verified by two certificates. One of the certificates leads up to the Google certificate authority (CA), and the other certificate leads up to the Cavium CA.

Retrieve the certificate chain for the CA that you want to use.
```
curl -O https://www.gstatic.com/cloudhsm/cloud-kms-prod-[LOCATION]-[google|cavium].pem
```
Replace [LOCATION] with one of the regions supported by Cloud HSM. Replace [google|cavium] with either google or cavium. Here's an example for the us-west location and the Google CA:
```
curl -O https://www.gstatic.com/cloudhsm/cloud-kms-prod-us-west1-google.pem
```
To display the contents of the certificate, run:
```
openssl x509 -in cloud-kms-prod-[LOCATION]-[google|cavium].pem -text
```
Install the Python wrapper for OpenSSL.
```
pip install --user pyopenssl
```
At the Cloud Shell command-line prompt, run the verification tool.
```
python verify.py \
  cloud-kms-prod-[LOCATION]-[google|cavium].pem \
  [KEYRING]-[KEY]-[KEYVERSION]-[ATTESTATION-FORMAT]-attestation.dat
```
The verification tool verifies the signature included at the end of the attestation file with the public key provided in the HSM certificate bundle. The bundle currently contains all certificate chains from all HSMs up to but not including the certificate authority (CA) certificate.

Verifying values in the attestation file

In addition to verifying the signature for the attestation, you can verify other parts of the attestation. For example, you can verify the key version ID in the attestation with the key version ID that is viewable in Key Management Service.

If you are parsing an attestation that is in the CAVIUM_V1_COMPRESSED format, run the following:

python parse_v1.py [symmetric|asymmetric] \
[KEYRING]-[KEY]-[KEYVERSION]-[ATTESTATION-FORMAT]-attestation.dat > parsed.dat

If you are parsing an attestation that is in the CAVIUM_V2_COMPRESSED format, run the following:

python parse_v2.py \
[KEYRING]-[KEY]-[KEYVERSION]-[ATTESTATION-FORMAT]-attestation.dat > parsed.dat

The parsed.dat file will be used for the following sections.

To verify the key 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] --key [KEY]
```

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]/cryptoKeys/[KEY]/cryptoKeyVersions/[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}')

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

echo $resource_name_hex | grep $keyid_hex
```

To verify key properties

You can view various key properties, for example, whether the key is extractable and what cryptographic operations are supported by the key. These properties correspond to fields in the PKCS #11 standard.

To determine whether a key is extractable, examine the 0x0162 field:

grep '0x0162:' parsed.dat

To determine the key type, examine the 0x0100 field. Key types are also enumerated in the PCKS#11 standard with prefix CKK_*.

grep '0x0100:' parsed.dat

To determine if a key was imported, examine the 0x0163 field. The attribute is true for keys created using Cloud HSM, and false for imported keys.

grep '0x0163:' parsed.dat

To verify the public key

For asymmetric keys, you can verify that the key pair generated matches the public key. You can compare the Key Checksum Value (KCV) and Extended KCV (EKCV) of the public key and match them with what is present in the attestation.

Retrieve the public key locally.
```
gcloud kms keys versions get-public-key \
  [KEY_VERSION] --location [LOCATION] \
  --keyring [KEY_RING] --key [KEY] \
  --output-file /tmp/key.pub
```
In addition to using the gcloud command-line tool, you can retrieve the public key usingthe Cloud Console and the KMS API.

Run the script to verify the public key.

python verify_pubkey.py parsed.dat /tmp/key.pub

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 KMS API, or the gcloud tool.