Importação de chaves resistente a ataques quânticos

Visualizar

Este produto ou recurso está sujeito aos "Termos das Soluções Pré-GA" na seção "Termos Gerais de Serviço" dos Termos Específicos de Serviço. Os produtos e recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

Neste guia, mostramos como importar uma chave criptográfica para o Cloud Key Management Service como uma nova versão de chave usando um método de importação resistente a ataques quânticos. Essa abordagem ajuda a proteger a chave durante o trânsito contra ataques de "coleta agora, descriptografia depois" (HNDL, na sigla em inglês) por futuros computadores quânticos.

A importação de chaves resistentes a ataques quânticos usa ferramentas padrão de criptografia pós-quântica (PQC), incluindo mecanismos de encapsulamento de chaves (KEMs) e criptografia de chave pública híbrida (HPKE), para proteger sua chave durante o trânsito.

A importação de chaves resistente a ataques quânticos é compatível com chaves protegidas por software (nível de proteção SOFTWARE).

Antes de começar

Antes de importar uma chave, você precisa preparar o projeto, o sistema local e o material da chave.

Preparar o projeto

Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloud, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the required API.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the API

Instale a CLI do Google Cloud.

Ao usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.

Para inicializar a CLI gcloud, execute o seguinte comando:

gcloud init

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the required API.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the API

Instale a CLI do Google Cloud.

Ao usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.

Para inicializar a CLI gcloud, execute o seguinte comando:

gcloud init

Funções exigidas

Para receber as permissões necessárias para importar uma chave, peça ao administrador que conceda a você os seguintes papéis do IAM no keyring:

• Para importar apenas para chaves atuais: Cloud KMS Importer (roles/cloudkms.importer)
• Para importar para novas chaves: Administrador do Cloud KMS (roles/cloudkms.admin)

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Preparar o sistema local

Você precisa de uma biblioteca criptográfica no seu sistema local que seja compatível com ferramentas de criptografia pós-quântica (PQC), incluindo mecanismos de encapsulamento de chaves (KEMs) e criptografia híbrida de chave pública (HPKE). Você pode usar o Tink, o OpenSSL ou outra biblioteca de criptografia que ofereça suporte ao seguinte:

• Criptografia de chave pública híbrida (HPKE)
• Um dos seguintes algoritmos de KEM:
  • ML-KEM-768
  • ML-KEM-1024
  • X-WING (um híbrido de ML-KEM-768 e X25519)
• A função de derivação de chaves (KDF, na sigla em inglês) HKDF-SHA256
• Criptografia autenticada com dados associados (AEAD) usando o algoritmo AES-256-GCM

Preparar a chave

Verifique se o algoritmo e o comprimento da chave são compatíveis. Todas as versões de uma chave precisam ter o mesmo nível de proteção (SOFTWARE).

Criar a chave e o keyring de segmentação

Quando você importa material de chave, ele se torna uma nova versão de uma chave existente. Essa chave é chamada de chave de destino. O keyring e a chave de destino precisam existir antes da importação do material da chave.

Siga estas etapas para criar uma chave vazia com suporte de software em um novo keyring usando a Google Cloud CLI ou o console Google Cloud .

Console

1. No console do Google Cloud , acesse a página Gerenciamento de chaves.

   Vá para Gerenciamento de chaves

2. Clique em Criar keyring.

3. No campo Nome do keyring, digite o nome do seu keyring.

4. Em Tipo de local, selecione um tipo e um local.

5. Clique em Criar. A página Criar chave é aberta.

6. No campo Nome da chave, insira o nome da sua chave.

7. Em Nível de proteção, selecione Software.

8. Em Material da chave, selecione Chave importada e clique em Continuar. Isso impede que uma versão de chave inicial seja criada.

9. Defina a Finalidade e o Algoritmo da chave e clique em Continuar.

10. Opcional: se você quiser que essa chave contenha apenas versões importadas, selecione Restringir versões de chave apenas à importação. Isso evita que você crie acidentalmente novas versões de chave no Cloud KMS.

11. Opcional: para chaves importadas, a rotação automática é desativada por padrão. Para ativar a rotação de chaves automática, selecione um valor no campo Período de rotação de chaves.

    Se você ativar a rotação automática, as novas versões das chaves serão geradas no Cloud KMS, e a versão importada da chave não será mais a versão padrão da chave após uma rotação.

12. Clique em Criar.

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.

1. Crie o keyring de segmentação. Escolha um local compatível com o nível de proteção que você quer usar. Para mais informações sobre os locais compatíveis, consulte Locais do Cloud KMS.

   gcloud kms keyrings create KEY_RING \
     --location LOCATION
   

   Saiba mais sobre como criar keyring.

2. Crie a chave de destino usando o comando kms keys create com a flag --skip-initial-version-creation. Isso cria uma chave sem versão inicial para que o material de chave importado seja a versão 1. Use a flag --import-only para impedir que o Cloud KMS gere material de chave para novas versões de chave. Com essa flag definida, novas versões da chave precisam ser importadas. As chaves criadas como --import-only precisam ser giradas manualmente.

   gcloud kms keys create KEY_NAME \
     --location LOCATION \
     --keyring KEY_RING \
     --purpose PURPOSE \
     --protection-level SOFTWARE \
     --skip-initial-version-creation \
     --import-only
   

   Substitua:

   • KEY_NAME: o nome que você quer usar para a chave.
   • LOCATION: a localização do keyring.
   • KEY_RING: o keyring em que você quer criar a chave.
   • PURPOSE: a finalidade que você quer usar para a chave.

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.

1. Crie um novo keyring:

   curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings?keyRingId=KEY_RING" \
       --request "POST" \
       --header "authorization: Bearer TOKEN" \
       --header "content-type: application/json" \
       --header "x-goog-user-project: PROJECT_ID" \
       --data "{}"
   

   Consulte a documentação da API KeyRing.create para mais informações.

2. Crie uma chave vazia, apenas para importação:

   curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys?cryptoKeyId=KEY_NAME&skipInitialVersionCreation=true" \
       --request "POST" \
       --header "authorization: Bearer TOKEN" \
       --header "content-type: application/json" \
       --header "x-goog-user-project: PROJECT_ID" \
       --data "{"purpose":"PURPOSE", "importOnly": "true", "versionTemplate":{"protectionLevel":"PROTECTION_LEVEL","algorithm":"ALGORITHM"}}"
   

   Consulte a documentação da API CryptoKey.create para mais informações.

Agora o keyring e a chave existem, mas a chave não contém material de chave, não tem versão e não está ativa. Em seguida, crie um job de importação.

Criar o job de importação

Um job de importação define as características das chaves importadas, incluindo o nível de proteção e o método de importação.

A importação de chaves resistente a ataques quânticos é compatível apenas com o nível de proteção SOFTWARE. Escolha um dos seguintes métodos de importação resistente a ataques quânticos:

• HPKE_KEM_XWING_HKDF_SHA256_AES_256_GCM
• HPKE_KEM_ML_KEM_768_HKDF_SHA256_AES_256_GCM

• HPKE_KEM_ML_KEM_1024_HKDF_SHA256_AES_256_GCM

gcloud

Execute o comando a seguir para criar um job de importação com um método de importação resistente a ataques quânticos:

gcloud kms import-jobs create IMPORT_JOB \
    --location LOCATION \
    --keyring KEY_RING \
    --import-method IMPORT_METHOD \
    --protection-level software

Substitua:

• IMPORT_JOB: um nome exclusivo para usar no job de importação.
• LOCATION: o local do keyring em que você criou a chave de destino.
• KEY_RING: o nome do keyring em que você criou a chave de destino.
• IMPORT_METHOD: o método de importação resistente a ataques quânticos que você quer usar, por exemplo, hpke-kem-xwing-hkdf-sha256-aes-256-gcm.

REST

Chame o método keyRings.importJobs.create:

curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/importJobs?import_job_id=IMPORT_JOB" \
    --request "POST" \
    --header "authorization: Bearer TOKEN" \
    --header "content-type: application/json" \
    --data '{"import_method": "IMPORT_METHOD", "protection_level": "SOFTWARE"}'

Substitua:

• PROJECT_ID: o identificador do seu projeto do Cloud KMS.
• LOCATION: o local do keyring em que você criou a chave de destino.
• KEY_RING: o nome do keyring em que você criou a chave de destino.
• IMPORT_JOB: um nome exclusivo para usar no job de importação.
• TOKEN: o token para autenticar a solicitação.
• IMPORT_METHOD: o método de importação resistente a ataques quânticos que você quer usar, por exemplo, HPKE_KEM_XWING_HKDF_SHA256_AES_256_GCM.

Verificar o estado do job de importação

O estado inicial de um job de importação é PENDING_GENERATION. Quando o estado é ACTIVE, você pode usá-lo para importar chaves.

Um job de importação expira após três dias. Se o job de importação tiver expirado, você precisará criar um novo.

É possível verificar o status de um job de importação usando a Google Cloud CLI, o consoleGoogle Cloud ou a API Cloud Key Management Service.

Console

1. Acesse a página Gerenciamento de chaves no console do Google Cloud .

   Acessar a página "Gerenciamento de chaves"

2. Clique no nome do keyring que contém o job de importação.

3. Clique na guia Jobs de importação na parte superior da página.

4. O estado ficará visível em Status, ao lado do nome do job de importação.

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.

Quando um job de importação está ativo, você pode usá-lo para importar chaves. Talvez isso leve alguns minutos. Use este comando para verificar se o job de importação está ativo. Use o local e o keyring em que você criou o job de importação.

gcloud kms import-jobs describe IMPORT_JOB \
  --location LOCATION \
  --keyring KEY_RING \
  --format="value(state)"

O resultado será o seguinte:

state: ACTIVE

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"
	"io"

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

// checkStateImportJob checks the state of an ImportJob in KMS.
func checkStateImportJob(w io.Writer, name string) error {
	// name := "projects/PROJECT_ID/locations/global/keyRings/my-key-ring/importJobs/my-import-job"

	// 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()

	// Call the API.
	result, err := client.GetImportJob(ctx, &kmspb.GetImportJobRequest{
		Name: name,
	})
	if err != nil {
		return fmt.Errorf("failed to get import job: %w", err)
	}
	fmt.Fprintf(w, "Current state of import job %q: %s\n", result.Name, result.State)
	return nil
}

Java

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

import com.google.cloud.kms.v1.ImportJob;
import com.google.cloud.kms.v1.ImportJobName;
import com.google.cloud.kms.v1.KeyManagementServiceClient;
import java.io.IOException;

public class CheckStateImportJob {

  public void checkStateImportJob() throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";
    String locationId = "us-east1";
    String keyRingId = "my-key-ring";
    String importJobId = "my-import-job";
    checkStateImportJob(projectId, locationId, keyRingId, importJobId);
  }

  // Check the state of an import job in Cloud KMS.
  public void checkStateImportJob(
      String projectId, String locationId, String keyRingId, String importJobId)
      throws IOException {
    // Initialize client that will be used to send requests. This client only
    // needs to be created once, and can be reused for multiple requests. After
    // completing all of your requests, call the "close" method on the client to
    // safely clean up any remaining background resources.
    try (KeyManagementServiceClient client = KeyManagementServiceClient.create()) {
      // Build the parent name from the project, location, and key ring.
      ImportJobName importJobName = ImportJobName.of(projectId, locationId, keyRingId, importJobId);

      // Retrieve the state of an existing import job.
      ImportJob importJob = client.getImportJob(importJobName);
      System.out.printf(
          "Current state of import job %s: %s%n", importJob.getName(), importJob.getState());
    }
  }
}

Node.js

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

//
// TODO(developer): Uncomment these variables before running the sample.
//
// const projectId = 'my-project';
// const locationId = 'us-east1';
// const keyRingId = 'my-key-ring';
// const importJobId = 'my-import-job';

// Imports the Cloud KMS library
const {KeyManagementServiceClient} = require('@google-cloud/kms');

// Instantiates a client
const client = new KeyManagementServiceClient();

// Build the import job name
const importJobName = client.importJobPath(
  projectId,
  locationId,
  keyRingId,
  importJobId
);

async function checkStateImportJob() {
  const [importJob] = await client.getImportJob({
    name: importJobName,
  });

  console.log(
    `Current state of import job ${importJob.name}: ${importJob.state}`
  );
  return importJob;
}

return checkStateImportJob();

Python

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

from google.cloud import kms


def check_state_import_job(
    project_id: str, location_id: str, key_ring_id: str, import_job_id: str
) -> None:
    """
    Check the state of an import job in Cloud KMS.

    Args:
        project_id (string): Google Cloud project ID (e.g. 'my-project').
        location_id (string): Cloud KMS location (e.g. 'us-east1').
        key_ring_id (string): ID of the Cloud KMS key ring (e.g. 'my-key-ring').
        import_job_id (string): ID of the import job (e.g. 'my-import-job').
    """

    # Create the client.
    client = kms.KeyManagementServiceClient()

    # Retrieve the fully-qualified import_job string.
    import_job_name = client.import_job_path(
        project_id, location_id, key_ring_id, import_job_id
    )

    # Retrieve the state from an existing import job.
    import_job = client.get_import_job(name=import_job_name)

    print(f"Current state of import job {import_job.name}: {import_job.state}")

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.

Para verificar o estado de um job de importação, use o método ImportJobs.get:

curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/importJobs/IMPORT_JOB_ID" \
    --request "GET" \
    --header "authorization: Bearer TOKEN"

Assim que o job de importação estiver ativo, você poderá fazer uma solicitação para importar uma chave.

Recuperar a chave pública de encapsulamento

Depois que o job de importação for ACTIVE, recupere a chave pública associada a ele. Você vai usar essa chave pública no sistema local para unir o material de chave que quer importar.

gcloud

Execute o comando a seguir para fazer o download da chave pública:

gcloud kms import-jobs describe IMPORT_JOB 

    --location LOCATION 

    --keyring KEY_RING 

    --format="value(publicKey.data)"

Substitua:

• IMPORT_JOB: o nome do job de importação.
• LOCATION: o local do keyring em que você criou o job de importação.
• KEY_RING: o nome do keyring em que você criou o job de importação.

A chave pública é codificada em base64.

REST

1. Chame o método keyRings.importJobs.get.
2. Recupere a chave pública do campo publicKey.data da resposta e salve-a localmente como public_key.data.

Preparar e encapsular o material de chave

Use uma biblioteca criptográfica externa compatível no seu sistema local para unir o material de chave usando a chave de união pública recuperada.

O processo de encapsulamento precisa executar HPKE.Seal() (RFC 9180) para produzir uma chave encapsulada. Isso conclui as seguintes etapas:

1. Encapsule a chave pública recuperada para produzir uma senha secreta e uma chave de encapsulamento.
2. Derive uma chave simétrica efêmera da chave secreta compartilhada usando HKDF-SHA256.
3. Criptografe o material da chave com a chave efêmera usando AES-256-GCM.
4. Concatene a chave de encapsulamento e o material de chave criptografado como texto criptografado. Essa é a chave encapsulada resultante que você vai usar para importar a chave. Salve como wrapped_key.bin.

O exemplo de código Go a seguir demonstra como encapsular material de chave usando a biblioteca tink-go:

package main

import (
    "bytes"
    "encoding/base64"
    "flag"
    "fmt"
    "log"

    "google.golang.org/protobuf/proto"
    "github.com/tink-crypto/tink-go/v2/hybrid"
    "github.com/tink-crypto/tink-go/v2/keyset"

    hpkepb "github.com/tink-crypto/tink-go/v2/proto/hpke_go_proto"
    tinkpb "github.com/tink-crypto/tink-go/v2/proto/tink_go_proto"
)

var (
    publicKeyB64Flag = flag.String("public_key", "", "Base64 encoded public key for wrapping.")
    targetKeyB64Flag = flag.String("target_key", "", "Base64 encoded 32-byte target key to be wrapped.")
)

func main() {
    flag.Parse()

    if *publicKeyB64Flag == "" {
        log.Fatal("-public_key is required")
    }
    if *targetKeyB64Flag == "" {
        log.Fatal("-target_key is required")
    }

    pkBytes, err := base64.StdEncoding.DecodeString(*publicKeyB64Flag)
    if err != nil {
        log.Fatalf("failed to decode public key: %v", err)
    }

    targetKey, err := base64.StdEncoding.DecodeString(*targetKeyB64Flag)
    if err != nil {
        log.Fatalf("failed to decode target key: %v", err)
    }

    hpkePubKey := &hpkepb.HpkePublicKey{
        Version: 0,
        Params: &hpkepb.HpkeParams{
            Kem:  hpkepb.HpkeKem_ML_KEM768,
            Kdf:  hpkepb.HpkeKdf_HKDF_SHA256,
            Aead: hpkepb.HpkeAead_AES_256_GCM,
        },
        PublicKey: pkBytes,
    }
    serializedPubKey, err := proto.Marshal(hpkePubKey)
    if err != nil {
        log.Fatalf("failed to marshal HPKE public key: %v", err)
    }

    ks := &tinkpb.Keyset{
        PrimaryKeyId: 1,
        Key: []*tinkpb.Keyset_Key{
            {
                KeyData: &tinkpb.KeyData{
                    TypeUrl:         "type.googleapis.com/google.crypto.tink.HpkePublicKey",
                    Value:           serializedPubKey,
                    KeyMaterialType: tinkpb.KeyData_ASYMMETRIC_PUBLIC,
                },
                Status:           tinkpb.KeyStatusType_ENABLED,
                KeyId:            1,
                OutputPrefixType: tinkpb.OutputPrefixType_RAW,
            },
        },
    }
    serializedKeyset, err := proto.Marshal(ks)
    if err != nil {
        log.Fatalf("failed to marshal keyset: %v", err)
    }

    // Create a KeysetHandle and retrieve the HybridEncrypt primitive.
    reader := keyset.NewBinaryReader(bytes.NewReader(serializedKeyset))
    handle, err := keyset.ReadWithNoSecrets(reader)
    if err != nil {
        log.Fatalf("failed to create keyset handle: %v", err)
    }

    enc, err := hybrid.NewHybridEncrypt(handle)
    if err != nil {
        log.Fatalf("failed to create hybrid encrypt primitive: %v", err)
    }

    // Perform the wrapping operation. Tink's HPKE implementation handles the
  // 'enc || ciphertext' concatenation automatically.
    wrappedKey, err := enc.Encrypt(targetKey, nil)
    if err != nil {
        log.Fatalf("failed to wrap key: %v", err)
    }

    fmt.Printf("Final wrappedKey (base64):\n%s\n", base64.StdEncoding.EncodeToString(wrappedKey))
}

Salve a string base64 de saída ou decodifique-a em um arquivo binário: bash echo "BASE64_WRAPPED_KEY" | base64 --decode > wrapped_key.bin

Observação:durante a visualização, só é possível importar chaves pré-encapsuladas. O encapsulamento automático de chaves não é compatível.

Importar a chave encapsulada

Importe a chave encapsulada preparada como uma nova versão da chave de destino.

gcloud

Execute o comando kms keys versions import:

gcloud kms keys versions import \
    --location LOCATION \
    --keyring KEY_RING \
    --key KEY_NAME \
    --import-job IMPORT_JOB \
    --algorithm ALGORITHM \
    --wrapped-key-file wrapped_key.bin

Substitua:

• LOCATION: a localização do keyring que contém a chave de destino.
• KEY_RING: o nome do keyring que contém a chave de destino.
• KEY_NAME: o nome da chave de destino.
• IMPORT_JOB: o nome do job de importação.
• ALGORITHM: o algoritmo do material da chave a ser importado.

REST

Chame o método cryptoKeyVersions.import:

curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME/cryptoKeyVersions:import" \
    --request "POST" \
    --header "authorization: Bearer TOKEN" \
    --header "content-type: application/json" \
    --data '{"importJob": "IMPORT_JOB", "algorithm": "ALGORITHM", "wrappedKey": "PATH_TO_WRAPPED_KEY"}'

Substitua:

• PROJECT_ID: o identificador do seu projeto do Cloud KMS.
• LOCATION: a localização do keyring que contém a chave de destino.
• KEY_RING: o nome do keyring que contém a chave de destino.
• KEY_NAME: o nome da chave de destino.
• TOKEN: o token para autenticar a solicitação.
• IMPORT_JOB: o identificador do job de importação correspondente.
• ALGORITHM: o algoritmo do material da chave a ser importado.
• PATH_TO_WRAPPED_KEY: o caminho para sua chave encapsulada manualmente no formato Base64.

Verificar o estado da versão da chave importada

O estado inicial de uma versão de chave importada é PENDING_IMPORT. Quando o estado é ENABLED, a versão da chave foi importada. Se a importação falhar, o status será IMPORT_FAILED.

É possível verificar o status de uma solicitação de importação usando a Google Cloud CLI, o console doGoogle Cloud ou a API Cloud Key Management Service.

Console

1. Abra a página Gerenciamento de chaves no console doGoogle Cloud .

2. Clique no nome do keyring que contém o job de importação.

3. Clique na guia Jobs de importação na parte superior da página.

4. O estado ficará visível em Status, ao lado do nome do job de importação.

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.

Use o comando versions list para verificar o estado. Use o mesmo local, keyring e chave de destino que você criou anteriormente neste tópico.

gcloud kms keys versions list \
  --keyring KEY_RING \
  --location LOCATION \
  --key KEY_NAME

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"
	"io"

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

// checkStateImportedKey checks the state of a CryptoKeyVersion in KMS.
func checkStateImportedKey(w io.Writer, name string) error {
	// name := "projects/PROJECT_ID/locations/global/keyRings/my-key-ring/cryptoKeys/my-imported-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()

	// Call the API.
	result, err := client.GetCryptoKeyVersion(ctx, &kmspb.GetCryptoKeyVersionRequest{
		Name: name,
	})
	if err != nil {
		return fmt.Errorf("failed to get crypto key version: %w", err)
	}
	fmt.Fprintf(w, "Current state of crypto key version %q: %s\n", result.Name, result.State)
	return nil
}

Java

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

import com.google.cloud.kms.v1.CryptoKeyVersion;
import com.google.cloud.kms.v1.CryptoKeyVersionName;
import com.google.cloud.kms.v1.KeyManagementServiceClient;
import java.io.IOException;

public class CheckStateImportedKey {

  public void checkStateImportedKey() throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";
    String locationId = "us-east1";
    String keyRingId = "my-key-ring";
    String cryptoKeyId = "my-crypto-key";
    String cryptoKeyVersionId = "1";
    checkStateImportedKey(projectId, locationId, keyRingId, cryptoKeyId, cryptoKeyVersionId);
  }

  // Check the state of an imported key in Cloud KMS.
  public void checkStateImportedKey(
      String projectId,
      String locationId,
      String keyRingId,
      String cryptoKeyId,
      String cryptoKeyVersionId)
      throws IOException {
    // Initialize client that will be used to send requests. This client only
    // needs to be created once, and can be reused for multiple requests. After
    // completing all of your requests, call the "close" method on the client to
    // safely clean up any remaining background resources.
    try (KeyManagementServiceClient client = KeyManagementServiceClient.create()) {
      // Build the version name from its path components.
      CryptoKeyVersionName versionName =
          CryptoKeyVersionName.of(
              projectId, locationId, keyRingId, cryptoKeyId, cryptoKeyVersionId);

      // Retrieve the state of an existing version.
      CryptoKeyVersion version = client.getCryptoKeyVersion(versionName);
      System.out.printf(
          "Current state of crypto key version %s: %s%n", version.getName(), version.getState());
    }
  }
}

Node.js

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

//
// TODO(developer): Uncomment these variables before running the sample.
//
// const projectId = 'my-project';
// const locationId = 'us-east1';
// const keyRingId = 'my-key-ring';
// const cryptoKeyId = 'my-imported-key';
// const cryptoKeyVersionId = '1';

// Imports the Cloud KMS library
const {KeyManagementServiceClient} = require('@google-cloud/kms');

// Instantiates a client
const client = new KeyManagementServiceClient();

// Build the key version name
const keyVersionName = client.cryptoKeyVersionPath(
  projectId,
  locationId,
  keyRingId,
  cryptoKeyId,
  cryptoKeyVersionId
);

async function checkStateCryptoKeyVersion() {
  const [keyVersion] = await client.getCryptoKeyVersion({
    name: keyVersionName,
  });

  console.log(
    `Current state of key version ${keyVersion.name}: ${keyVersion.state}`
  );
  return keyVersion;
}

return checkStateCryptoKeyVersion();

Python

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

from google.cloud import kms


def check_state_imported_key(
    project_id: str, location_id: str, key_ring_id: str, import_job_id: str
) -> None:
    """
    Check the state of an import job in Cloud KMS.

    Args:
        project_id (string): Google Cloud project ID (e.g. 'my-project').
        location_id (string): Cloud KMS location (e.g. 'us-east1').
        key_ring_id (string): ID of the Cloud KMS key ring (e.g. 'my-key-ring').
        import_job_id (string): ID of the import job (e.g. 'my-import-job').
    """

    # Create the client.
    client = kms.KeyManagementServiceClient()

    # Retrieve the fully-qualified import_job string.
    import_job_name = client.import_job_path(
        project_id, location_id, key_ring_id, import_job_id
    )

    # Retrieve the state from an existing import job.
    import_job = client.get_import_job(name=import_job_name)

    print(f"Current state of import job {import_job.name}: {import_job.state}")

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.

Chame o método ImportJob.get e verifique o campo [state][api_importjob_fields_state]. Se state for PENDING_GENERATION, o job de importação ainda está sendo criado. Verifique periodicamente o estado até que ele seja ACTIVE.

Depois que a versão inicial da chave é importada, o status dela muda para ENABLED. Para chaves simétricas, você precisa definir a versão da chave importada como a versão principal antes de usar a chave.

Importar novamente uma chave destruída anteriormente

Se você precisar restaurar uma versão de chave importada anteriormente que esteja no estado DESTROYED ou IMPORT_FAILED para o estado ENABLED, reimporte o mesmo material de chave.

A reimportação de uma versão de chave destruída usa o mesmo procedimento da importação inicial, usando o job de importação original ou um novo (com o mesmo nível de proteção SOFTWARE).

Observação:não é possível reimportar uma chave usando um método resistente a ataques quânticos se a versão original foi importada com um método baseado em criptografia RSA.