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 compatibles con 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

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

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

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 el siguiente contenido:

#!/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 el siguiente contenido:

#!/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

A fin de facilitar la verificación de una clave pública, crea un archivo llamado verify_pubkey.py que contenga lo siguiente:

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

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

1. Ve a la página Claves criptográficas en GCP Console.
   Ir a la página Claves criptográficas
   

2. Haz clic en el nombre del llavero de claves que contiene la clave cuya versión quieres certificar.

3. Haz clic en la clave cuya versión quieres certificar.

4. Ubica la versión de clave que quieres certificar y haz clic en el ícono Más (3 puntos verticales).

5. Haz clic en Obtener certificación.

6. En el diálogo Obtener certificación, haz clic en Descargar. El archivo de certificación se descargará en tu computadora.

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

Línea de comandos

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

2. En la línea de comandos de Cloud Shell, usa el comando gcloud kms keys versions describe para recuperar el formato de certificación de 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.

3. En la línea de comandos de Cloud Shell, usa el comando gcloud kms keys versions describe a fin de recuperar la certificación de la clave que quieres certificar, con el formato de certificación que recuperaste en el paso anterior en lugar de [ATTESTATION-FORMAT]. La marca --attestation-file especifica la ruta de acceso y el destino del nombre del archivo 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.

1. 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. Reemplaza [google|cavium] por google o cavium. En el siguiente ejemplo, se usa 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
   

2. Instala el wrapper de Python para OpenSSL.

   pip install --user pyopenssl
   

3. 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 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 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á para las siguientes secciones.

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 de recurso de la clave forma 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 de recurso de la clave.

1. 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]
   

2. En la línea de comandos, asigna resource_name al 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]
   

3. 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 la 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 también 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.

1. 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, puedes recuperar la clave pública con GCP Console y la API de Cloud KMS.

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