Encapsula y desencapsula con KEM

En este documento, se describe el uso de mecanismos de encapsulación de claves (KEM) con claves de Cloud KMS para establecer secretos compartidos.

La encapsulación usa la clave pública del par de claves del KEM, y la desencapsulación usa la clave privada del par de claves. Cloud KMS te permite recuperar la clave pública, que luego 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 comenzar

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

Otorga permisos en la clave

• Otorga el rol roles/cloudkms.publicKeyViewer en la clave a cada usuario o principal que deba recuperar la clave pública para encapsular el secreto.
• Otorga el rol "roles/cloudkms.decapsulator" en la clave a cada usuario o principal que deba desencapsular secretos con esta clave.

Para obtener más información sobre los permisos y las funciones en Cloud KMS, consulta Permisos y funciones.

Encapsulamiento

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

gcloud

Esta muestra requiere OpenSSL para instalarse 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

Reemplaza lo siguiente:

• KEY_VERSION: Es el número de versión de la clave que deseas usar para la encapsulación, por ejemplo, 2.
• KEY_NAME: Es el nombre de la clave que deseas usar para la encapsulación.
• KEY_RING: el nombre del llavero de claves que incluye la clave
• LOCATION: la ubicación de Cloud KMS del llavero de claves.
• PUBLIC_KEY_FILE: Es la ruta de acceso al archivo local en el que se guardará la clave pública.
• PUBLIC_KEY_FORMAT: Es 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

Reemplaza lo siguiente:

• PEM_PUBLIC_KEY_FILE: Es la ruta al archivo de clave pública descargado en formato PEM.
• CIPHERTEXT_FILE: Es la ruta de acceso en la que deseas guardar el texto cifrado resultante.
• SHARED_SECRET_FILE: Es la ruta de acceso en la que deseas guardar el secreto compartido resultante.

Nota: Este comando requiere que la clave pública esté en formato PEM. Si descargaste la clave pública en otro formato, como nist-pqc, debes convertirla al formato PEM. Por ejemplo, para ML-KEM-768, puedes usar el siguiente comando:

{ echo -n "MIIEsjALBglghkgBZQMEBAIDggShAA==" | base64 -d ; cat PUBLIC_KEY_FILE; } | \
openssl pkey -inform DER -pubin -pubout -out PEM_PUBLIC_KEY_FILE

Reemplaza lo siguiente:

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

Decapsulació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 Google Cloud CLI.

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

Reemplaza lo siguiente:

• KEY_VERSION: Es la versión de la clave que se usará para la desencapsulación, por ejemplo, 3.
• KEY_NAME: Es el nombre de la clave que se usará para la desencapsulación.
• KEY_RING: Es el nombre del llavero de claves en el que se encuentra la llave.
• LOCATION: Es la ubicación de Cloud KMS del llavero de claves.
• CIPHERTEXT_FILE: Es la ruta de acceso del archivo local para el texto cifrado de entrada.
• SHARED_SECRET_FILE: Es la ruta de acceso al archivo local para guardar el secreto compartido de salida.

API

En estos ejemplos, se usa curl como un cliente HTTP para demostrar el uso de la API. Para obtener más información sobre el control de acceso, consulta Accede a la API de 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"}'

Reemplaza lo siguiente:

• PROJECT_ID: Es el ID del proyecto que contiene el llavero de claves.
• LOCATION: la ubicación de Cloud KMS del llavero de claves.
• KEY_RING: el nombre del llavero de claves que incluye la clave
• KEY_NAME: Es el nombre de la clave que se usará para la encriptación.
• KEY_VERSION: Es el ID de la versión de la clave que se usará para la encriptación.
• CIPHERTEXT: Es el texto cifrado codificado en Base64 que deseas desencapsular.