Esta página foi traduzida pela API Cloud Translation.

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

Conceda a função roles/cloudkms.publicKeyViewer na chave a cada usuário ou principal que precisa recuperar a chave pública para encapsular o secret.
Conceda o papel roles/cloudkms.decapsulator na chave a cada usuário ou principal que precisa desencapsular secrets com ela.

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.

Reformatar a chave pública

O comando "encapsulate" exige que a chave pública esteja no formato PEM. Se você baixou a chave pública em outro formato, como nist-pqc, é necessário convertê-la para o formato PEM. Se a chave pública já estiver no formato PEM, continue em Encapsular.

Use o comando a seguir para converter a chave pública de uma chave ML-KEM-768:

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

Use o comando a seguir para converter a chave pública de uma chave ML-KEM-1024:

{ echo -n "MIIGMjALBglghkgBZQMEBAMDggYhAA==" | 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.

Encapsular

Para criar um segredo compartilhado 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.

Go

Para executar esse código, primeiro configure um ambiente de desenvolvimento Go e instale o SDK do Cloud KMS para Go.

import (
	"context"
	"crypto/mlkem"
	"fmt"
	"hash/crc32"
	"io"

	kms "cloud.google.com/go/kms/apiv1"
	"cloud.google.com/go/kms/apiv1/kmspb"
)

// encapsulateMLKEM demonstrates how to encapsulate a shared secret using an ML-KEM-768 public key
// from Cloud KMS.
func encapsulateMLKEM(w io.Writer, keyVersionName string) error {
	// keyVersionName := "projects/my-project/locations/us-east1/keyRings/my-key-ring/cryptoKeys/my-key/cryptoKeyVersions/1"

	// Create the client.
	ctx := context.Background()
	client, err := kms.NewKeyManagementClient(ctx)
	if err != nil {
		return fmt.Errorf("failed to create kms client: %w", err)
	}
	defer client.Close()

	// crc32c calculates the CRC32C checksum of the given data.
	crc32c := func(data []byte) uint32 {
		t := crc32.MakeTable(crc32.Castagnoli)
		return crc32.Checksum(data, t)
	}

	// Build the request to get the public key in NIST PQC format.
	req := &kmspb.GetPublicKeyRequest{
		Name:            keyVersionName,
		PublicKeyFormat: kmspb.PublicKey_NIST_PQC,
	}

	// Call the API to get the public key.
	response, err := client.GetPublicKey(ctx, req)
	if err != nil {
		return fmt.Errorf("failed to get public key: %w", err)
	}

	// Optional, but recommended: perform integrity verification on the response.
	// For more details on ensuring E2E in-transit integrity to and from Cloud KMS visit:
	// https://cloud.google.com/kms/docs/data-integrity-guidelines
	if response.GetName() != req.GetName() {
		return fmt.Errorf("GetPublicKey: request corrupted in-transit")
	}
	if response.GetPublicKeyFormat() != req.GetPublicKeyFormat() {
		return fmt.Errorf("GetPublicKey: request corrupted in-transit")
	}
	if int64(crc32c(response.GetPublicKey().GetData())) != response.GetPublicKey().GetCrc32CChecksum().GetValue() {
		return fmt.Errorf("GetPublicKey: response corrupted in-transit")
	}

	// Use the public key with crypto/mlkem to encapsulate a shared secret.
	ek, err := mlkem.NewEncapsulationKey768(response.GetPublicKey().GetData())
	if err != nil {
		return fmt.Errorf("NewEncapsulationKey768: %w", err)
	}
	sharedSecret, ciphertext := ek.Encapsulate()

	fmt.Fprintf(w, "Encapsulated ciphertext: %x\n", ciphertext)
	fmt.Fprintf(w, "Shared secret: %x\n", sharedSecret)
	return nil
}

Decapsulagem

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.

Go

Para executar esse código, primeiro configure um ambiente de desenvolvimento Go e instale o SDK do Cloud KMS para Go.

import (
	"context"
	"fmt"
	"hash/crc32"
	"io"

	kms "cloud.google.com/go/kms/apiv1"
	"cloud.google.com/go/kms/apiv1/kmspb"
	"google.golang.org/protobuf/types/known/wrapperspb"
)

// decapsulate decapsulates the given ciphertext using a saved private key of purpose
// KEY_ENCAPSULATION stored in KMS.
func decapsulate(w io.Writer, keyVersionName string, ciphertext []byte) error {
	// keyVersionName := "projects/my-project/locations/us-east1/keyRings/my-key-ring/cryptoKeys/my-key/cryptoKeyVersions/1"
	// ciphertext := []byte("...")

	// Create the client.
	ctx := context.Background()
	client, err := kms.NewKeyManagementClient(ctx)
	if err != nil {
		return fmt.Errorf("failed to create kms client: %w", err)
	}
	defer client.Close()

	// crc32c calculates the CRC32C checksum of the given data.
	crc32c := func(data []byte) uint32 {
		t := crc32.MakeTable(crc32.Castagnoli)
		return crc32.Checksum(data, t)
	}

	// Optional but recommended: Compute ciphertext's CRC32C.
	ciphertextCRC32C := crc32c(ciphertext)

	// Build the request.
	req := &kmspb.DecapsulateRequest{
		Name:             keyVersionName,
		Ciphertext:       ciphertext,
		CiphertextCrc32C: wrapperspb.Int64(int64(ciphertextCRC32C)),
	}

	// Call the API.
	result, err := client.Decapsulate(ctx, req)
	if err != nil {
		return fmt.Errorf("failed to decapsulate: %w", err)
	}

	// Optional, but recommended: perform integrity verification on the response.
	// For more details on ensuring E2E in-transit integrity to and from Cloud KMS visit:
	// https://cloud.google.com/kms/docs/data-integrity-guidelines
	if !result.GetVerifiedCiphertextCrc32C() {
		return fmt.Errorf("Decapsulate: request corrupted in-transit")
	}
	if result.GetName() != req.GetName() {
		return fmt.Errorf("Decapsulate: request corrupted in-transit")
	}
	if int64(crc32c(result.GetSharedSecret())) != result.GetSharedSecretCrc32C() {
		return fmt.Errorf("Decapsulate: response corrupted in-transit")
	}

	fmt.Fprintf(w, "Decapsulated plaintext: %x", result.GetSharedSecret())
	return nil
}

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.

Encapsular e desencapsular usando KEMs Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Antes de começar

Conceder permissões na chave

Encapsulamento

gcloud

Baixar a chave pública

Reformatar a chave pública

Encapsular

Go

Decapsulagem

gcloud

Go

API

Encapsular e desencapsular usando KEMs