Encapsular e desencapsular usando KEMs

Este documento descreve o uso de mecanismos de encapsulamento de chaves (KEMs, na sigla em inglês) com chaves do Cloud KMS para estabelecer segredos compartilhados.

O encapsulamento usa a chave pública do par de chaves do KEM, e o desencapsulamento usa a chave privada. O Cloud KMS permite recuperar a chave pública, que pode ser usada com bibliotecas padrão para encapsular seu segredo compartilhado. Para desencapsular o segredo compartilhado, use os métodos de desencapsulamento do Cloud KMS. Não é possível usar o material da chave privada fora do Cloud KMS.

Antes de começar

  • Este documento fornece exemplos que são executados na linha de comando. Para simplificar o uso dos exemplos, use o Cloud Shell. No exemplo de criptografia, usamos o OpenSSL, que é pré-instalado no Cloud Shell. Caso contrário, instale o OpenSSL na sua máquina.
  • Crie uma chave KEM com a finalidade de chave de KEY_ENCAPSULATION. Para ver quais algoritmos são compatíveis com a finalidade de chave KEY_ENCAPSULATION, consulte algoritmos de encapsulamento de chave.

Conceder permissões na chave

Para mais informações sobre permissões e papéis no Cloud KMS, consulte Permissões e papéis.

Encapsulamento

Para encapsular usando uma chave KEM, recupere a chave pública e use-a para encapsular.

gcloud

Este exemplo requer a instalação do OpenSSL no sistema local.

Baixar a chave 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

Substitua:

  • KEY_VERSION: o número da versão da chave que você quer usar para encapsulamento. Por exemplo, 2.
  • KEY_NAME: o nome da chave que você quer usar para encapsulamento.
  • KEY_RING: o nome do keyring que contém a chave.
  • LOCATION: o local do Cloud KMS do keyring.
  • PUBLIC_KEY_FILE: o caminho do arquivo local em que a chave pública será salva.
  • PUBLIC_KEY_FORMAT: o formato de destino da chave pública, por exemplo, nist-pqc. O formato padrão é pem.

Encapsular

Para criar uma chave secreta compartilhada e um texto criptografado, use o seguinte comando:

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

Substitua:

  • PEM_PUBLIC_KEY_FILE: o caminho para o arquivo de chave pública baixado no formato PEM.
  • CIPHERTEXT_FILE: o caminho onde você quer salvar o texto cifrado resultante.
  • SHARED_SECRET_FILE: o caminho onde você quer salvar o secret compartilhado resultante.
{ echo -n "MIIEsjALBglghkgBZQMEBAIDggShAA==" | base64 -d ; cat PUBLIC_KEY_FILE; } | \
openssl pkey -inform DER -pubin -pubout -out PEM_PUBLIC_KEY_FILE

Substitua:

  • PUBLIC_KEY_FILE: o caminho para o arquivo de chave pública baixado no formato bruto.
  • PEM_PUBLIC_KEY_FILE: o caminho e o nome do arquivo para salvar a chave pública no formato PEM.

Decapsulação

Use o Cloud KMS para desencapsular um texto cifrado.

gcloud

Para usar o Cloud KMS na linha de comando, primeiro instale ou faça upgrade para a versão mais recente da 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

Substitua:

  • KEY_VERSION: a versão da chave a ser usada para desencapsulamento. Por exemplo, 3.
  • KEY_NAME: o nome da chave a ser usada para desencapsulamento.
  • KEY_RING: o nome do keyring em que a chave está localizada.
  • LOCATION: o local do Cloud KMS para o keyring.
  • CIPHERTEXT_FILE: o caminho do arquivo local para o texto criptografado de entrada.
  • SHARED_SECRET_FILE: o caminho do arquivo local para salvar o segredo compartilhado de saída.

API

Estes exemplos usam curl como um cliente HTTP para demonstrar o uso da API. Para mais informações sobre controle de acesso, consulte Como acessar a API Cloud KMS.

Use o 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"}'

Substitua:

  • PROJECT_ID: o ID do projeto que contém o keyring.
  • LOCATION: o local do Cloud KMS do keyring.
  • KEY_RING: o nome do keyring que contém a chave.
  • KEY_NAME: o nome da chave a ser usada para criptografia.
  • KEY_VERSION: o ID da versão da chave a ser usada para criptografia
  • CIPHERTEXT: o texto cifrado codificado em base64 que você quer desencapsular.