Encapsule e desencapsule com KEMs

Este documento descreve a utilização de mecanismos de encapsulamento de chaves (KEMs) com chaves do Cloud KMS para estabelecer segredos partilhados.

A encapsulação usa a chave pública do par de chaves KEM e a desencapsulação usa a chave privada do par de chaves. O Cloud KMS permite-lhe obter a chave pública, que pode usar com bibliotecas padrão para encapsular o seu segredo partilhado. Para desencapsular o segredo partilhado, use os métodos de desencapsulamento do Cloud KMS. Não pode 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 comandos. Para simplificar a utilização dos exemplos, use a Cloud Shell. O exemplo de encriptação usa o OpenSSL, que está pré-instalado no Cloud Shell. Caso contrário, instale o OpenSSL no seu computador.
  • Crie uma chave KEM com a finalidade da chave de KEY_ENCAPSULATION. Para ver que algoritmos são suportados para a finalidade da chave KEY_ENCAPSULATION, consulte os algoritmos de encapsulamento de chaves.

Conceda autorizações na chave

Para mais informações acerca das autorizações e funções no Cloud KMS, consulte o artigo Autorizações e funções.

Encapsulamento

Para encapsular através de uma chave KEM, obtenha a chave pública e use-a para encapsular.

gcloud

Este exemplo requer que o OpenSSL esteja instalado no seu sistema local.

Transfira 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 o seguinte:

  • KEY_VERSION: o número da versão da chave que quer usar para a encapsulagem, por exemplo, 2.
  • KEY_NAME: o nome da chave que quer usar para a encapsulagem.
  • KEY_RING: o nome do conjunto de chaves que contém a chave.
  • LOCATION: a localização do Cloud KMS do conjunto de chaves.
  • PUBLIC_KEY_FILE: o caminho do ficheiro local onde a chave pública vai ser guardada.
  • PUBLIC_KEY_FORMAT: o formato de destino da chave pública, por exemplo, nist-pqc. O formato predefinido é pem.

Encapsular

Para criar um segredo partilhado e um texto cifrado, pode usar o seguinte comando:

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

Substitua o seguinte:

  • PEM_PUBLIC_KEY_FILE: o caminho para o ficheiro de chave pública transferido no formato PEM.
  • CIPHERTEXT_FILE: O caminho onde quer guardar o texto cifrado resultante.
  • SHARED_SECRET_FILE: o caminho onde quer guardar o segredo partilhado resultante.
{ echo -n "MIIEsjALBglghkgBZQMEBAIDggShAA==" | base64 -d ; cat PUBLIC_KEY_FILE; } | \
openssl pkey -inform DER -pubin -pubout -out PEM_PUBLIC_KEY_FILE

Substitua o seguinte:

  • PUBLIC_KEY_FILE: o caminho para o ficheiro de chave pública transferido no formato não processado.
  • PEM_PUBLIC_KEY_FILE: o caminho e o nome do ficheiro para guardar 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 comandos, primeiro instale ou atualize para a versão mais recente da CLI do 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

Substitua o seguinte:

  • KEY_VERSION: a versão da chave a usar para a desencapsulagem. Por exemplo, 3.
  • KEY_NAME: o nome da chave a usar para a desencapsulagem.
  • KEY_RING: o nome do conjunto de chaves onde a chave se encontra.
  • LOCATION: a localização do Cloud KMS para o conjunto de chaves.
  • CIPHERTEXT_FILE: o caminho do ficheiro local para o texto cifrado de entrada.
  • SHARED_SECRET_FILE: o caminho do ficheiro local para guardar o símbolo secreto partilhado de saída.

API

Estes exemplos usam o curl como cliente HTTP para demonstrar a utilização da API. Para mais informações sobre o controlo de acesso, consulte o artigo Aceder à 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 o seguinte:

  • PROJECT_ID: o ID do projeto que contém o conjunto de chaves.
  • LOCATION: a localização do Cloud KMS do conjunto de chaves.
  • KEY_RING: o nome do conjunto de chaves que contém a chave.
  • KEY_NAME: o nome da chave a usar para a encriptação.
  • KEY_VERSION: o ID da versão da chave a usar para a encriptação
  • CIPHERTEXT: o texto cifrado codificado em base64 que quer desencapsular.