Encapsular y desencapsular con KEMs

En este documento se describe cómo usar mecanismos de encapsulado de claves (KEMs) con claves de Cloud KMS para establecer secretos compartidos.

El encapsulado usa la clave pública del par de claves KEM, y el desencapsulado usa la clave privada del par de claves. Cloud KMS te permite recuperar la clave pública, que puedes usar con bibliotecas estándar para encapsular tu secreto compartido. Para desencapsular el secreto compartido, usa los métodos de desencapsulación de Cloud KMS. No puedes usar el material de la clave privada fuera de Cloud KMS.

Antes de empezar

  • En este documento se proporcionan ejemplos que se ejecutan en la línea de comandos. Para simplificar el uso de los ejemplos, utiliza Cloud Shell. En el ejemplo de cifrado se usa OpenSSL, que viene preinstalado en Cloud Shell. De lo contrario, instala OpenSSL en tu máquina.
  • Crea una clave KEM con el propósito de la clave KEY_ENCAPSULATION. Para ver qué algoritmos se admiten para el propósito de clave KEY_ENCAPSULATION, consulta los algoritmos de encapsulación de claves.

Concede permisos en la clave

Para obtener más información sobre los permisos y los roles de Cloud KMS, consulta Permisos y roles.

Encapsulación

Para encapsular con una clave KEM, recupera la clave pública y úsala para encapsular.

gcloud

Para usar este ejemplo, debes tener OpenSSL instalado en tu sistema local.

Descarga la clave pública

gcloud kms keys versions get-public-key KEY_VERSION \
    --key KEY_NAME \
    --keyring KEY_RING \
    --location LOCATION  \
    --output-file PUBLIC_KEY_FILE \
    --public-key-format PUBLIC_KEY_FORMAT

Haz los cambios siguientes:

  • KEY_VERSION: el número de versión de la clave que quieras usar para el encapsulado. Por ejemplo, 2.
  • KEY_NAME: El nombre de la clave que quieras usar para la encapsulación.
  • KEY_RING: el nombre del conjunto de claves que contiene la clave.
  • LOCATION: la ubicación de Cloud KMS del conjunto de claves.
  • PUBLIC_KEY_FILE: ruta del archivo local donde se guardará la clave pública.
  • PUBLIC_KEY_FORMAT: el formato de destino de la clave pública (por ejemplo, nist-pqc). El formato predeterminado es pem.

Encapsular

Para crear un secreto compartido y un texto cifrado, puedes usar el siguiente comando:

openssl pkeyutl \
    -encap \
    -pubin \
    -inkey PEM_PUBLIC_KEY_FILE \
    -out CIPHERTEXT_FILE \
    -secret SHARED_SECRET_FILE

Haz los cambios siguientes:

  • PEM_PUBLIC_KEY_FILE: ruta al archivo de clave pública descargado en formato PEM.
  • CIPHERTEXT_FILE: la ruta en la que quieres guardar el texto cifrado resultante.
  • SHARED_SECRET_FILE: la ruta en la que quieres guardar el secreto compartido resultante.
{ echo -n "MIIEsjALBglghkgBZQMEBAIDggShAA==" | base64 -d ; cat PUBLIC_KEY_FILE; } | \
openssl pkey -inform DER -pubin -pubout -out PEM_PUBLIC_KEY_FILE

Haz los cambios siguientes:

  • PUBLIC_KEY_FILE: la ruta al archivo de clave pública descargado en formato sin procesar.
  • PEM_PUBLIC_KEY_FILE: ruta y nombre del archivo para guardar la clave pública en formato PEM.

Desencapsulación

Usa Cloud KMS para desencapsular un texto cifrado.

gcloud

Para usar Cloud KMS en la línea de comandos, primero instala o actualiza a la versión más reciente de la CLI de Google Cloud.

gcloud kms decapsulate \
    --version KEY_VERSION \
    --key KEY_NAME \
    --keyring KEY_RING \
    --location LOCATION  \
    --ciphertext-file CIPHERTEXT_FILE \
    --shared-secret-file SHARED_SECRET_FILE

Haz los cambios siguientes:

  • KEY_VERSION: la versión de la clave que se va a usar para la desencapsulación. Por ejemplo, 3.
  • KEY_NAME: el nombre de la clave que se va a usar para desencapsular.
  • KEY_RING: el nombre del conjunto de claves en el que se encuentra la clave.
  • LOCATION: la ubicación de Cloud KMS del conjunto de claves.
  • CIPHERTEXT_FILE: la ruta del archivo local del texto cifrado de entrada.
  • SHARED_SECRET_FILE: la ruta del archivo local para guardar el secreto compartido de salida.

API

En estos ejemplos se usa curl como cliente HTTP para mostrar cómo se usa la API. Para obtener más información sobre el control de acceso, consulta el artículo sobre cómo acceder a la API Cloud KMS.

Usa el método CryptoKeyVersions.decapsulate.

curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME/cryptoKeyVersions/KEY_VERSION:decapsulate" \
  --request "POST" \
  --header "authorization: Bearer TOKEN" \
  --header "content-type: application/json" \
  --data '{"ciphertext": "CIPHERTEXT"}'

Haz los cambios siguientes:

  • PROJECT_ID: el ID del proyecto que contiene el conjunto de claves.
  • LOCATION: la ubicación de Cloud KMS del conjunto de claves.
  • KEY_RING: el nombre del conjunto de claves que contiene la clave.
  • KEY_NAME: el nombre de la clave que se va a usar para el cifrado.
  • KEY_VERSION: el ID de la versión de la clave que se va a usar para el cifrado.
  • CIPHERTEXT: el texto cifrado codificado en base64 que quieres desencapsular.