Verifica certificaciones

En el caso de las claves creadas en Cloud HSM, tienes la opción de solicitar una declaración de certificación para proporcionar evidencia de que la clave está protegida realmente por un HSM. La declaración es un token con una firma criptográfica que el hardware físico agrega directamente y que el usuario puede verificar. En esta página, se describe cómo verificar la firma de la declaración de certificación y determinar si la declaración coincide con la versión de clave.

Los ejemplos provistos corresponden a entornos de Linux.

Antes de comenzar

En esta página, se incluyen ejemplos en los que se usa la línea de comandos. Para hacerlo más simple, usaremos Cloud Shell. En el ejemplo de certificación, se usa OpenSSL, que viene instalado en Cloud Shell.
Si todavía no lo has hecho, crea un llavero de claves en una de las regiones admitidas por Cloud HSM y crea una clave que tenga el nivel de protección HSM.
Crea las siguientes secuencias de comandos de Python.

Secuencia de comandos para verificar una certificación

Crea el archivo verify.py en la línea de comandos en que verificarás la certificación a fin de facilitar el proceso. Si usas Cloud Shell, puedes usar el editor de código para crearlo. Usa el siguiente contenido en este archivo.

#!/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 SHA-256 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 kcv 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)

Secuencia de comandos para analizar una certificación

Hay dos secuencias de comandos diferentes para analizar una certificación, porque hay dos formatos de certificados, CAVIUM_V1_COMPRESSED y CAVIUM_V2_COMPRESSED.

Secuencia de comandos para analizar una certificación CAVIUM_V1_COMPRESSED

Crea un archivo llamado parse_v1.py con los siguientes contenidos:

#!/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):])

Secuencia de comandos para analizar una certificación CAVIUM_V2_COMPRESSED

Crea un archivo llamado parse_v2.py con los siguientes contenidos:

#!/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:])

Secuencia de comandos para verificar una clave pública

Crea un archivo llamado verify_pubkey.py que contenga el siguiente código a fin de facilitar la verificación de una clave pública.

#!/usr/bin/env python
import sys

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 SHA-256 digest of the key
  ekcv = hashlib.sha256(publickey).hexdigest()

  with open(parsed_attest_file, 'r') as parsed_attest_data:
    if kcv in parsed_attest_data.read() and ekcv in parsed_attest_data.read():
      print 'Public key matched with attestation.'
    else:
      print 'Public key not matched with attestation.'
      attest_lines = parsed_attest_data.readlines()
      # 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 if line.startswith('0x1003:'))]
      print(kcv_lines)

Recupera el archivo de certificación

Para recuperar la certificación de una versión de clave criptográfica, puedes usar Google Cloud Platform Console o la línea de comandos.

Console

Ve a la página Claves criptográficas de GCP Console.
Ir a la página Claves criptográficas
Haz clic en el nombre del llavero de claves que contiene la clave cuya versión quieres certificar.
Haz clic en la clave cuya versión quieres certificar.
Ubica la versión de clave que quieres certificar y haz clic en el ícono Más (3 puntos verticales).
Haz clic en Obtener certificación.
En el diálogo Obtener certificación, haz clic en Descargar. El archivo de certificación se descargará en tu computadora.

El formato para el nombre del archivo de certificación es [KEYRING]-[KEY]-[KEYVERSION]-[ATTESTATION-FORMAT]-attestation.dat.

Línea de comandos

Haz clic en el botón Activar Google Cloud Shell en la parte superior de la ventana de la consola. Se abrirá una sesión de Cloud Shell en un marco nuevo en la parte inferior de la consola, en la que se mostrará una línea de comandos. La sesión del shell puede tardar unos segundos en inicializarse.
En el mensaje de línea de comandos de Cloud Shell, usa el comando gcloud kms keys versions describe para recuperar el formato de certificación para la clave que quieres certificar.
```
gcloud kms keys versions describe [KEY_VERSION] \
  --key [KEY_NAME] \
  --location [LOCATION] \
  --keyring [KEY_RING]
```
El resultado de este comando muestra el formato de la certificación de la versión de clave, que necesitarás para el siguiente paso.
En el mensaje de línea de comandos de Cloud Shell, usa el comando gcloud kms keys versions describe a fin de recuperar el formato de certificación para la clave que quieres certificar, mediante el reemplazo de [ATTESTATION-FORMAT] con el formato de certificación que recuperaste en el paso anterior. La marca --attestation-file especifica el destino del nombre de archivo y la ruta de acceso para la certificación recuperada.
```
gcloud kms keys versions describe [KEY_VERSION] \
  --key [KEY_NAME] \
  --location [LOCATION] \
  --keyring [KEY_RING] \
  --attestation-file \
  [KEYRING]-[KEY]-[KEYVERSION]-[ATTESTATION-FORMAT]-attestation.dat
```

Certifica una clave

Puedes verificar la firma de una certificación mediante dos certificados: uno que pertenece a la autoridad certificada (CA) de Google y otro que pertenece a la CA de Cavium.

Recupera la cadena de certificados de la CA que quieres usar.
```
curl -O https://www.gstatic.com/cloudhsm/cloud-kms-prod-[LOCATION]-[google|cavium].pem
```
Reemplaza [LOCATION] por una de las regiones compatibles con Cloud HSM y [google|cavium] por google o cavium. En este ejemplo, se usan la ubicación us-west y la CA de Google:
```
curl -O https://www.gstatic.com/cloudhsm/cloud-kms-prod-us-west1-google.pem
```
Para mostrar el contenido del certificado, ejecuta este comando:
```
openssl x509 -in cloud-kms-prod-[LOCATION]-[google|cavium].pem -text
```
Instala el wrapper de Python para OpenSSL.
```
pip install --user pyopenssl
```
Ejecuta la herramienta de verificación en la ventana de la línea de comandos de Cloud Shell.
```
python verify.py \
  cloud-kms-prod-[LOCATION]-[google|cavium].pem \
  [KEYRING]-[KEY]-[KEYVERSION]-[ATTESTATION-FORMAT]-attestation.dat
```
La herramienta verifica la firma que está al final del archivo de certificación con la clave pública proporcionada en el paquete de certificados del HSM. En la actualidad, el paquete contiene todas las cadenas de certificados de todos los HSM, pero solo hasta el nivel anterior al certificado de la autoridad certificada (CA).

Verifica los valores del archivo de certificación

No solo puedes verificar la firma de la certificación, sino también otras partes de ella. Por ejemplo, puedes verificar el ID de la versión de clave de la certificación con el ID de la versión de clave que se puede ver en Cloud KMS.

Si analizas una certificación que está en formato CAVIUM_V1_COMPRESSED, ejecuta lo siguiente:

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

Si analizas una certificación que está en formato CAVIUM_V2_COMPRESSED, ejecuta lo siguiente:

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

El archivo parsed.dat se usará en las secciones posteriores.

Verifica el ID de la versión de clave

Puedes verificar si la certificación contiene el hash SHA-256 del ID de recurso de la versión de clave. El nombre del recurso de la clave es parte del campo 0x0102 o del campo de ID de clave en el archivo de certificación. El ID de clave se compone de dos resúmenes de hash SHA-256 concatenados en formato hexadecimal. El segundo debe coincidir con el nombre del recurso de la clave.

Obtén el ID de recurso de la versión de clave. Puedes usar GCP Console para obtener el ID de recurso de la versión de clave o ejecutar el siguiente comando de gcloud:
```
gcloud kms keys versions list \
  --location [LOCATION] \
  --keyring [KEY_RING] --key [KEY]
```

En la línea de comandos, asigna a resource_name el ID de recurso de la versión de clave que acabas de recuperar.

resource_name=projects/[PROJECT_ID]/locations/[LOCATION]/keyRings/[KEY_RING]/cryptoKeys/[KEY]/cryptoKeyVersions/[VERSION]

Ya que la secuencia de comandos de análisis vuelca todos los campos de certificación en formato hexadecimal, el ID de clave se habría formateado en formato hexadecimal dos veces (una vez durante la creación de keyID y la otra durante el análisis de la certificación). Para verificar que el nombre del recurso coincida con el ID de clave, convierte el nombre del recurso en un resumen hexadecimal SHA-256, revierte una conversión hexadecimal del ID de clave en el archivo de certificación y compara los dos.
```
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
```

Verifica las propiedades de la clave

Puedes ver varias propiedades de clave, como las operaciones criptográficas compatibles con la clave y la posibilidad de extraer la clave. Estas propiedades corresponden a los campos del estándar PKCS #11.

Para determinar si una clave se puede extraer, examina el campo 0x0162:

grep '0x0162:' parsed.dat

Para determinar el tipo de clave, examina el campo 0x0100. Además, los tipos de claves se enumeran en el estándar PCKS #11 con el prefijo CKK_*.

grep '0x0100:' parsed.dat

Para determinar si se importó una clave, examina el campo 0x0163. El atributo es verdadero para las claves creadas con Cloud HSM y falso para las claves importadas.

grep '0x0163:' parsed.dat

Verifica la clave pública

En el caso de las claves asimétricas, puedes verificar que el par de claves generado coincida con la clave pública. Puedes comparar el valor de la suma de verificación de la clave (KCV) y el KCV extendido (EKCV) de la clave pública con el contenido de la certificación.

Recupera la clave pública de manera local.
```
gcloud kms keys versions get-public-key \
  [KEY_VERSION] --location [LOCATION] \
  --keyring [KEY_RING] --key [KEY] \
  --output-file /tmp/key.pub
```
Además de usar gcloud, también puedes recuperar la clave pública mediante GCP Console y la API de Cloud KMS.
Ejecuta la secuencia de comandos para verificar la clave pública.
```
python verify_pubkey.py parsed.dat /tmp/key.pub
```

Información adicional

Puedes verificar una certificación para determinar si una versión de clave se creó dentro de un HSM. Dado que la verificación es independiente de Google de manera intencional, no puedes verificar una certificación mediante Google Cloud Platform Console, la API de Cloud KMS ni la línea de comandos de gcloud.