Importe uma versão de chave para o Cloud KMS

Este guia mostra como importar uma chave criptográfica para o Cloud HSM ou o Cloud Key Management Service como uma nova versão da chave.

Para ver mais detalhes sobre a importação de chaves, incluindo limitações e restrições, consulte o artigo Importação de chaves.

Pode concluir os passos neste guia em 5 a 10 minutos, sem incluir os passos da secção Antes de começar. A união da chave adiciona manualmente complexidade à tarefa.

Antes de começar

Recomendamos que crie um novo projeto para testar esta funcionalidade, para facilitar a limpeza após o teste e garantir que tem autorizações de gestão de identidade e de acesso (IAM) adequadas para importar uma chave.

Antes de poder importar uma chave, tem de preparar o projeto, o sistema local e a própria chave.

A preparar o projeto

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

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 Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

Install the Google Cloud CLI.

Se estiver a usar um fornecedor de identidade (IdP) externo, tem primeiro de iniciar sessão na CLI gcloud com a 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 Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

Install the Google Cloud CLI.

Se estiver a usar um fornecedor de identidade (IdP) externo, tem primeiro de iniciar sessão na CLI gcloud com a sua identidade federada.

Para inicializar a CLI gcloud, execute o seguinte comando:

gcloud init

1. O utilizador que realiza a importação precisa das seguintes autorizações do IAM para criar conjuntos de chaves, chaves e tarefas de importação. Se o utilizador não for o proprietário do projeto, pode atribuir-lhe ambas as seguintes funções predefinidas:

   • roles/editor
   • roles/cloudkms.importer

   Para mais informações sobre as funções e as autorizações de IAM disponíveis para o Cloud KMS, consulte o artigo Autorizações e funções.

Preparar o sistema local

Prepare o sistema local escolhendo uma das seguintes opções. A união automática de chaves é recomendada para a maioria dos utilizadores.

• Se quiser permitir que a CLI Google Cloud envolva as suas chaves automaticamente antes de as transmitir para Google Cloud, tem de instalar a biblioteca de criptografia Pyca no seu sistema local. A biblioteca Pyca é usada pela tarefa de importação que envolve e protege a chave localmente antes de a enviar para o Google Cloud.
• Se quiser encapsular as chaves manualmente, tem de configurar o OpenSSL para o encapsulamento manual de chaves.

A preparar a chave

Verifique se o algoritmo e o comprimento da chave são suportados. Os algoritmos permitidos para uma chave dependem de se a chave é usada para encriptação simétrica, encriptação assimétrica ou assinatura assimétrica, bem como se a chave está armazenada num software ou num HSM. Especifica o algoritmo da chave como parte do pedido de importação.

Em separado, também tem de verificar como a chave está codificada e fazer ajustes, se necessário.

Não é possível alterar o seguinte para uma versão da chave depois de criada ou importada:

• O nível de proteção indica se a chave persiste no software, num HSM multi-inquilino, num HSM de inquilino único ou num sistema de gestão de chaves externo. Não é possível mover material de chaves de um destes ambientes de armazenamento para outro. Todas as versões de uma chave têm o mesmo nível de proteção.

• O objetivo indica se as versões da chave são usadas para encriptação simétrica, encriptação assimétrica ou assinatura assimétrica. A finalidade da chave limita os possíveis algoritmos que podem ser usados para criar versões dessa chave. Todas as versões de uma chave têm o mesmo objetivo.

Se não tiver uma chave para importar, mas quiser validar o procedimento de importação de chaves, pode criar uma chave simétrica no sistema local através do seguinte comando:

openssl rand 32 > ${HOME}/test.bin

Use esta chave apenas para testes. Uma chave criada desta forma pode não ser adequada para utilização em produção.

Se precisar de encapsular a chave manualmente, faça-o antes de continuar com os procedimentos neste guia.

Crie a chave de destino e o conjunto de chaves

Uma chave do Cloud KMS é um objeto de contentor que contém zero ou mais versões da chave. Cada versão da chave contém uma chave criptográfica.

Quando importa uma chave para o Cloud KMS ou o Cloud HSM, a chave importada torna-se uma nova versão de chave numa chave do Cloud KMS ou do Cloud HSM existente. No resto deste guia, esta chave é denominada chave de destino. A chave de destino tem de existir antes de poder importar material de chaves para a mesma.

A importação de uma versão de chave não tem efeito nas versões existentes dessa chave. No entanto, é recomendável criar uma chave vazia quando testar a importação de chaves. Uma chave vazia não tem versão, não está ativa e não pode ser usada.

Opcionalmente, pode especificar que a chave recém-criada só pode conter versões importadas, o que impede a geração acidental de novas versões no Cloud KMS.

Existe uma chave num conjunto de chaves. Neste guia, este conjunto de chaves é denominado conjunto de chaves de destino. A localização do conjunto de chaves de destino determina a localização onde o material da chave está disponível após a importação. Não é possível criar nem importar chaves do Cloud HSM em algumas localizações. Depois de criar uma chave, não a pode mover para um anel de chaves ou uma localização diferente.

Siga estes passos para criar uma chave vazia num novo conjunto de chaves através da CLI Google Cloud ou da consola Google Cloud .

Consola

1. Na Google Cloud consola, aceda à página Gestão de chaves.

   Aceda à gestão de chaves

2. Clique em Criar conjunto de chaves.

3. No campo Nome do conjunto de chaves, introduza o nome do conjunto de chaves.

4. Em Tipo de localização, selecione um tipo de localização e uma localização.

5. Clique em Criar. É apresentada a página Criar chave.

6. No campo Nome da chave, introduza o nome da chave.

7. Para o Nível de proteção, selecione Software, HSM ou HSM de inquilino único.

8. Se selecionou HSM de inquilino único, selecione a instância do HSM de inquilino único onde quer criar a chave.

9. Em Material essencial, selecione Chave importada e, de seguida, clique em Continuar. Isto impede a criação de uma versão inicial da chave.

10. Defina o Objetivo e o Algoritmo da chave e, de seguida, clique em Continuar.

11. Opcional: se quiser que esta chave contenha apenas versões de chaves importadas, selecione Restringir versões de chaves apenas à importação. Isto evita que crie acidentalmente novas versões de chaves no Cloud KMS.

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

    Se ativar a rotação automática, são geradas novas versões da chave no Cloud KMS, e a versão da chave importada deixa de ser a versão da chave predefinida após uma rotação.

13. Clique em Criar.

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.

1. Crie o conjunto de chaves de destino. Escolha uma localização compatível com o nível de proteção que quer usar. Para mais informações sobre as localizações suportadas, consulte o artigo Localizações do Cloud KMS.

   gcloud kms keyrings create KEY_RING \
     --location LOCATION
   

   Pode saber mais sobre a criação de conjuntos de chaves.

2. Crie a chave de destino com o comando kms keys create e a flag --skip-initial-version-creation. Isto cria uma chave sem versão inicial da chave para que o material da chave importada 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 chaves. Com esta flag definida, têm de ser importadas novas versões da chave para esta chave. As chaves criadas como --import-only têm de ser rodadas manualmente.

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

   Substitua o seguinte:

   • KEY_NAME: o nome que quer usar para a chave.
   • LOCATION: a localização do conjunto de chaves.
   • KEY_RING: o conjunto de chaves onde quer criar a chave.
   • PURPOSE: a finalidade que quer usar para a chave.
   • PROTECTION_LEVEL: o nível de proteção que quer usar para a chave, por exemplo, HSM.

   Para criar uma chave do Cloud HSM de inquilino único, adicione a flag --cryptoKeyBackend a este comando e adicione o identificador de recurso da instância do Cloud HSM de inquilino único onde quer importar a chave:

   --crypto-key-backend="projects/INSTANCE_PROJECT/locations/LOCATION/singleTenantHsmInstances/INSTANCE_NAME"

Go

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

import (
	"context"
	"fmt"
	"io"

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

// createKeyForImport creates a new asymmetric signing key in Cloud HSM.
func createKeyForImport(w io.Writer, parent, id string) error {
	// parent := "projects/my-project/locations/us-east1/keyRings/my-key-ring"
	// id := "my-imported-key"

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

	// Build the request.
	req := &kmspb.CreateCryptoKeyRequest{
		Parent:      parent,
		CryptoKeyId: id,
		CryptoKey: &kmspb.CryptoKey{
			Purpose: kmspb.CryptoKey_ASYMMETRIC_SIGN,
			VersionTemplate: &kmspb.CryptoKeyVersionTemplate{
				ProtectionLevel: kmspb.ProtectionLevel_HSM,
				Algorithm:       kmspb.CryptoKeyVersion_EC_SIGN_P256_SHA256,
			},
			// Ensure that only imported versions may be added to this key.
			ImportOnly: true,
		},
		SkipInitialVersionCreation: true,
	}

	// Call the API.
	result, err := client.CreateCryptoKey(ctx, req)
	if err != nil {
		return fmt.Errorf("failed to create key: %w", err)
	}
	fmt.Fprintf(w, "Created key: %s\n", result.Name)
	return nil
}

Java

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

import com.google.cloud.kms.v1.CreateCryptoKeyRequest;
import com.google.cloud.kms.v1.CryptoKey;
import com.google.cloud.kms.v1.CryptoKey.CryptoKeyPurpose;
import com.google.cloud.kms.v1.CryptoKeyVersion.CryptoKeyVersionAlgorithm;
import com.google.cloud.kms.v1.CryptoKeyVersionTemplate;
import com.google.cloud.kms.v1.KeyManagementServiceClient;
import com.google.cloud.kms.v1.KeyRingName;
import com.google.cloud.kms.v1.ProtectionLevel;
import java.io.IOException;

public class CreateKeyForImport {

  public void createKeyForImport() 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 id = "my-import-key";
    createKeyForImport(projectId, locationId, keyRingId, id);
  }

  // Create a new crypto key to hold imported key versions.
  public void createKeyForImport(String projectId, String locationId, String keyRingId, String id)
      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.
      KeyRingName keyRingName = KeyRingName.of(projectId, locationId, keyRingId);

      // Create the crypto key.
      CryptoKey createdKey =
          client.createCryptoKey(
              CreateCryptoKeyRequest.newBuilder()
                  .setParent(keyRingName.toString())
                  .setCryptoKeyId(id)
                  .setCryptoKey(
                      CryptoKey.newBuilder()
                          .setPurpose(CryptoKeyPurpose.ASYMMETRIC_SIGN)
                          .setVersionTemplate(
                              CryptoKeyVersionTemplate.newBuilder()
                                  .setProtectionLevel(ProtectionLevel.HSM)
                                  .setAlgorithm(CryptoKeyVersionAlgorithm.EC_SIGN_P256_SHA256))
                          // Ensure that only imported versions may be
                          // added to this key.
                          .setImportOnly(true))
                  .setSkipInitialVersionCreation(true)
                  .build());

      System.out.printf("Created crypto key %s%n", createdKey.getName());
    }
  }
}

Node.js

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

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

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

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

// Build the parent key ring name
const keyRingName = client.keyRingPath(projectId, locationId, keyRingId);

async function createKeyForImport() {
  const [key] = await client.createCryptoKey({
    parent: keyRingName,
    cryptoKeyId: id,
    cryptoKey: {
      purpose: 'ENCRYPT_DECRYPT',
      versionTemplate: {
        algorithm: 'GOOGLE_SYMMETRIC_ENCRYPTION',
        protectionLevel: 'HSM',
      },
      // Optional: ensure that only imported versions may be added to this
      // key.
      importOnly: true,
    },
    // Do not allow KMS to generate an initial version of this key.
    skipInitialVersionCreation: true,
  });

  console.log(`Created key for import: ${key.name}`);
  return key;
}

return createKeyForImport();

Python

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

from google.cloud import kms


def create_key_for_import(
    project_id: str, location_id: str, key_ring_id: str, crypto_key_id: str
) -> None:
    """

    Sets up an empty CryptoKey within a KeyRing for import.


    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').
        crypto_key_id (string): ID of the key to import (e.g. 'my-asymmetric-signing-key').
    """

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

    # Build the key. For more information regarding allowed values of these fields, see:
    # https://googleapis.dev/python/cloudkms/latest/_modules/google/cloud/kms_v1/types/resources.html
    purpose = kms.CryptoKey.CryptoKeyPurpose.ASYMMETRIC_SIGN
    algorithm = kms.CryptoKeyVersion.CryptoKeyVersionAlgorithm.EC_SIGN_P256_SHA256
    protection_level = kms.ProtectionLevel.HSM
    key = {
        "purpose": purpose,
        "version_template": {
            "algorithm": algorithm,
            "protection_level": protection_level,
        },
    }

    # Build the parent key ring name.
    key_ring_name = client.key_ring_path(project_id, location_id, key_ring_id)

    # Call the API.
    created_key = client.create_crypto_key(
        request={
            "parent": key_ring_name,
            "crypto_key_id": crypto_key_id,
            "crypto_key": key,
            # Do not allow KMS to generate an initial version of this key.
            "skip_initial_version_creation": True,
        }
    )
    print(f"Created hsm key: {created_key.name}")

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.

1. Crie um novo conjunto de chaves:

   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 KeyRing.create documentação da API 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&importOnly=true" \
       --request "POST" \
       --header "authorization: Bearer TOKEN" \
       --header "content-type: application/json" \
       --header "x-goog-user-project: PROJECT_ID" \
       --data "{"purpose":"PURPOSE", "versionTemplate":{"protectionLevel":"PROTECTION_LEVEL","algorithm":"ALGORITHM"}}"
   

   Consulte a CryptoKey.create documentação da API para mais informações. Se quiser criar a chave num HSM na nuvem de inquilino único, adicione o campo cryptoKeyBackend ao corpo do comando e adicione o identificador do recurso da instância do HSM na nuvem de inquilino único onde quer importar a chave:

   "crypto-key-backend": "projects/INSTANCE_PROJECT/locations/LOCATION/singleTenantHsmInstances/INSTANCE_NAME"

O conjunto de chaves e a chave existem, mas a chave não contém material de chave, não tem uma versão e não está ativa. Em seguida, crie uma tarefa de importação.

Crie a tarefa de importação

Uma tarefa de importação define as caraterísticas das chaves que importa, incluindo propriedades que não podem ser alteradas após a importação da chave.

O nível de proteção define se as chaves importadas por esta tarefa de importação vão residir no software, num HSM multi-inquilino, num HSM de inquilino único ou num sistema de gestão de chaves externo. Não é possível alterar o nível de proteção depois de a chave ser importada.

O método de importação define o algoritmo usado para criar a chave de encapsulamento que protege as chaves importadas durante a transmissão do seu sistema local para o projeto Google Cloud de destino. Pode escolher uma chave RSA de 3072 bits ou 4096 bits. A menos que tenha requisitos específicos, recomendamos a chave de encapsulamento de 3072 bits.

Nota: o método de importação é diferente do algoritmo da chave a importar. O algoritmo da chave é especificado durante o pedido de importação.

Pode criar uma tarefa de importação através da CLI gcloud, da Google Cloud consola ou da API Cloud Key Management Service.

Consola

1. Aceda à página Gestão de chaves na Google Cloud consola.

   Aceda à página de gestão de chaves

2. Clique no nome do conjunto de chaves de destino.

3. Defina o Nível de proteção como Software, HSM ou HSM de inquilino único. Use o mesmo nível de proteção que definiu para a chave de destino.

4. Clique em Criar tarefa de importação.

5. No campo Nome, introduza o nome da tarefa de importação.

6. No menu pendente Método de importação, defina o método de importação como RSA de 3072 bits ou RSA de 4096 bits.

7. Clique em Criar.

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.

Use um comando como o seguinte para criar uma tarefa de importação.

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

• Use o mesmo conjunto de chaves e localização que a chave de destino.
• Defina o nível de proteção para o mesmo valor que usou para a chave de destino.
• Defina o método de importação para uma das seguintes opções:
  • rsa-oaep-3072-sha1-aes-256
  • rsa-oaep-4096-sha1-aes-256
  • rsa-oaep-3072-sha256-aes-256
  • rsa-oaep-4096-sha256-aes-256
  • rsa-oaep-3072-sha256
  • rsa-oaep-4096-sha256

Go

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

import (
	"context"
	"fmt"
	"io"

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

// createImportJob creates a new job for importing keys into KMS.
func createImportJob(w io.Writer, parent, id string) error {
	// parent := "projects/PROJECT_ID/locations/global/keyRings/my-key-ring"
	// id := "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()

	// Build the request.
	req := &kmspb.CreateImportJobRequest{
		Parent:      parent,
		ImportJobId: id,
		ImportJob: &kmspb.ImportJob{
			// See allowed values and their descriptions at
			// https://cloud.google.com/kms/docs/algorithms#protection_levels
			ProtectionLevel: kmspb.ProtectionLevel_HSM,
			// See allowed values and their descriptions at
			// https://cloud.google.com/kms/docs/key-wrapping#import_methods
			ImportMethod: kmspb.ImportJob_RSA_OAEP_3072_SHA1_AES_256,
		},
	}

	// Call the API.
	result, err := client.CreateImportJob(ctx, req)
	if err != nil {
		return fmt.Errorf("failed to create import job: %w", err)
	}
	fmt.Fprintf(w, "Created import job: %s\n", result.Name)
	return nil
}

Java

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

import com.google.cloud.kms.v1.ImportJob;
import com.google.cloud.kms.v1.ImportJob.ImportMethod;
import com.google.cloud.kms.v1.KeyManagementServiceClient;
import com.google.cloud.kms.v1.KeyRingName;
import com.google.cloud.kms.v1.ProtectionLevel;
import java.io.IOException;

public class CreateImportJob {

  public void createImportJob() 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 id = "my-import-job";
    createImportJob(projectId, locationId, keyRingId, id);
  }

  // Create a new import job.
  public void createImportJob(String projectId, String locationId, String keyRingId, String id)
      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.
      KeyRingName keyRingName = KeyRingName.of(projectId, locationId, keyRingId);

      // Build the import job to create, with parameters.
      ImportJob importJob =
          ImportJob.newBuilder()
              // See allowed values and their descriptions at
              // https://cloud.google.com/kms/docs/algorithms#protection_levels
              .setProtectionLevel(ProtectionLevel.HSM)
              // See allowed values and their descriptions at
              // https://cloud.google.com/kms/docs/key-wrapping#import_methods
              .setImportMethod(ImportMethod.RSA_OAEP_3072_SHA1_AES_256)
              .build();

      // Create the import job.
      ImportJob createdImportJob = client.createImportJob(keyRingName, id, importJob);
      System.out.printf("Created import job %s%n", createdImportJob.getName());
    }
  }
}

Node.js

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

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

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

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

// Build the parent key ring name
const keyRingName = client.keyRingPath(projectId, locationId, keyRingId);

async function createImportJob() {
  const [importJob] = await client.createImportJob({
    parent: keyRingName,
    importJobId: id,
    importJob: {
      protectionLevel: 'HSM',
      importMethod: 'RSA_OAEP_3072_SHA256',
    },
  });

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

return createImportJob();

Python

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

from google.cloud import kms


def create_import_job(
    project_id: str, location_id: str, key_ring_id: str, import_job_id: str
) -> None:
    """
    Create a new 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 key_ring string.
    key_ring_name = client.key_ring_path(project_id, location_id, key_ring_id)

    # Set paramaters for the import job, allowed values for ImportMethod and ProtectionLevel found here:
    # https://googleapis.dev/python/cloudkms/latest/_modules/google/cloud/kms_v1/types/resources.html

    import_method = kms.ImportJob.ImportMethod.RSA_OAEP_3072_SHA1_AES_256
    protection_level = kms.ProtectionLevel.HSM
    import_job_params = {
        "import_method": import_method,
        "protection_level": protection_level,
    }

    # Call the client to create a new import job.
    import_job = client.create_import_job(
        {
            "parent": key_ring_name,
            "import_job_id": import_job_id,
            "import_job": import_job_params,
        }
    )

    print(f"Created import job: {import_job.name}")

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.

Para criar uma tarefa de importação, use o método ImportJobs.create:

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

Substitua o seguinte:

• IMPORT_METHOD: um método de envolvimento de chaves suportado.
• PROTECTION_LEVEL: o nível de proteção das versões das chaves importadas por esta tarefa de importação.

Verificar o estado da tarefa de importação

O estado inicial de uma tarefa de importação é PENDING_GENERATION. Quando o estado é ACTIVE, pode usá-lo para importar chaves.

Uma tarefa de importação expira após três dias. Se a tarefa de importação tiver expirado, tem de criar uma nova.

Pode verificar o estado de uma tarefa de importação através da CLI Google Cloud, da Google Cloud consola ou da API Cloud Key Management Service.

Consola

1. Aceda à página Gestão de chaves na Google Cloud consola.

   Aceda à página Gestão de chaves

2. Clique no nome do conjunto de chaves que contém a tarefa de importação.

3. Clique no separador Tarefas de importação na parte superior da página.

4. O estado é visível em Estado junto ao nome da tarefa de importação.

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.

Quando uma tarefa de importação está ativa, pode usá-la para importar chaves. Esta ação pode demorar alguns minutos. Use este comando para verificar se a tarefa de importação está ativa. Use a localização e o conjunto de chaves onde criou a tarefa de importação.

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

O resultado é semelhante ao seguinte:

state: ACTIVE

Go

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

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 este código, primeiro configure um ambiente de desenvolvimento Java e instale o SDK Java do Cloud KMS.

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 este código, primeiro configure um ambiente de desenvolvimento do Node.js e instale o SDK do Node.js do Cloud KMS.

//
// 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 este código, primeiro configure um ambiente de desenvolvimento Python e instale o SDK Python do Cloud KMS.

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 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.

Para verificar o estado de uma tarefa 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 a tarefa de importação estiver ativa, pode fazer um pedido para importar uma chave.

Impedir a modificação de tarefas de importação

A tarefa de importação determina muitas caraterísticas da chave importada, incluindo o algoritmo da chave e se uma chave importada é uma chave HSM ou uma chave de software. Pode configurar autorizações da IAM para impedir que os utilizadores criem tarefas de importação, ao mesmo tempo que lhes permite usar tarefas de importação para importar chaves.

1. Conceda a autorização importjobs.create apenas aos administradores principais.
2. Conceda a autorização importjobs.useToImport para uma tarefa de importação específica ao operador que vai usar essa tarefa para importar chaves.
3. Quando cria a tarefa de importação, especifica o nível de proteção e o algoritmo para as versões das chaves importadas através da mesma.

Até que a tarefa de importação expire, os utilizadores que tenham a autorização importjobs.useToImport e não tenham a autorização importjobs.create para uma determinada tarefa de importação podem importar chaves, mas não podem modificar as caraterísticas da tarefa de importação.

Importe a chave

Depois de verificar o estado da tarefa de importação, pode fazer um pedido de importação.

Usa flags diferentes para fazer o pedido de importação, consoante queira que a Google Cloud CLI envolva a sua chave automaticamente ou se já envolveu a chave manualmente.

Independentemente de ter envolvido a chave manual ou automaticamente, tem de definir o algoritmo para um algoritmo suportado que corresponda ao comprimento da chave real a importar e especifica a finalidade da chave.

• As chaves com o objetivo ENCRYPT_DECRYPT usam o algoritmo google-symmetric-encryption e têm um comprimento de 32.

• As chaves com o objetivo ASYMMETRIC_DECRYPT ou ASYMMETRIC_SIGN suportam uma variedade de algoritmos e comprimentos.

  Não é possível alterar a finalidade de uma chave depois de a chave ser criada, mas podem ser criadas versões da chave subsequentes com comprimentos diferentes da versão da chave inicial.

Importante: tem de especificar o algoritmo e o comprimento reais da chave que está a importar. Para mais informações, consulte o artigo Preparar a chave.

Encapsulamento e importação automáticos de uma chave

Se quiser usar a união automática, tem de usar a CLI Google Cloud. Use um comando como o seguinte. Defina --target-key-file para a localização da chave não desembrulhada para embrulhar e importar. Não defina --wrapped-key-file.

Opcionalmente, pode definir a flag --public-key-file para a localização onde a chave pública já foi transferida. Quando importa um grande número de chaves, isto impede que a chave pública seja transferida durante cada importação. Por exemplo, pode escrever um script que transfira a chave pública uma vez e, em seguida, faculte a respetiva localização ao importar cada chave.

gcloud kms keys versions import \
    --import-job IMPORT_JOB \
    --location LOCATION \
    --keyring KEY_RING \
    --key KEY_NAME \
    --algorithm ALGORITHM \
    --target-key-file PATH_TO_UNWRAPPED_KEY

A chave é envolvida pela chave de envolvimento associada à tarefa de importação, transmitida para Google Cloude importada como uma nova versão da chave na chave de destino.

Importar uma chave envolvida manualmente

Siga as instruções nesta secção para importar uma chave que encapsulou manualmente. Defina --wrapped-key-file para a localização da chave que encapsulou manualmente. Não defina --target-key-file.

Opcionalmente, pode definir a flag --public-key-file para a localização onde a chave pública já foi transferida. Quando importa um grande número de chaves, isto impede que a chave pública seja transferida durante cada importação. Por exemplo, pode escrever um script que transfira a chave pública uma vez e, em seguida, faculte a respetiva localização quando importar cada chave.

Consola

1. Abra a página Gestão de chaves na Google Cloud consola.

2. Clique no nome do conjunto de chaves que contém a tarefa de importação. A chave de destino é apresentada juntamente com quaisquer outras chaves no porta-chaves.

3. Clique no nome da chave de segmentação e, de seguida, clique em Importar versão da chave.

4. Selecione a tarefa de importação no menu pendente Selecionar tarefa de importação.

5. No seletor Carregue a chave envolvida, selecione a chave que já envolveu.

6. Se estiver a importar uma chave assimétrica, selecione o algoritmo no menu pendente Algoritmo. A página Versão da chave de importação deve ter um aspeto semelhante ao seguinte:

   

7. Clique em Importar.

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.

Use um comando como o seguinte.

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

Para mais informações, consulte o resultado do comando gcloud kms keys versions import --help.

Go

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

import (
	"context"
	"crypto/ecdsa"
	"crypto/elliptic"
	"crypto/rand"
	"crypto/rsa"
	"crypto/sha1"
	"crypto/x509"
	"encoding/pem"
	"fmt"
	"io"

	kms "cloud.google.com/go/kms/apiv1"
	"cloud.google.com/go/kms/apiv1/kmspb"
	"github.com/google/tink/go/kwp/subtle"
)

// importManuallyWrappedKey wraps key material and imports it into KMS.
func importManuallyWrappedKey(w io.Writer, importJobName, cryptoKeyName string) error {
	// importJobName := "projects/PROJECT_ID/locations/global/keyRings/my-key-ring/importJobs/my-import-job"
	// cryptoKeyName := "projects/PROJECT_ID/locations/global/keyRings/my-key-ring/cryptoKeys/my-imported-key"

	// Generate a ECDSA keypair, and format the private key as PKCS #8 DER.
	key, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
	if err != nil {
		return fmt.Errorf("failed to generate keypair: %w", err)
	}
	keyBytes, err := x509.MarshalPKCS8PrivateKey(key)
	if err != nil {
		return fmt.Errorf("failed to format private key: %w", err)
	}

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

	// Generate a temporary 32-byte key for AES-KWP and wrap the key material.
	kwpKey := make([]byte, 32)
	if _, err := rand.Read(kwpKey); err != nil {
		return fmt.Errorf("failed to generate AES-KWP key: %w", err)
	}
	kwp, err := subtle.NewKWP(kwpKey)
	if err != nil {
		return fmt.Errorf("failed to create KWP cipher: %w", err)
	}
	wrappedTarget, err := kwp.Wrap(keyBytes)
	if err != nil {
		return fmt.Errorf("failed to wrap target key with KWP: %w", err)
	}

	// Retrieve the public key from the import job.
	importJob, err := client.GetImportJob(ctx, &kmspb.GetImportJobRequest{
		Name: importJobName,
	})
	if err != nil {
		return fmt.Errorf("failed to retrieve import job: %w", err)
	}
	pubBlock, _ := pem.Decode([]byte(importJob.PublicKey.Pem))
	pubAny, err := x509.ParsePKIXPublicKey(pubBlock.Bytes)
	if err != nil {
		return fmt.Errorf("failed to parse import job public key: %w", err)
	}
	pub, ok := pubAny.(*rsa.PublicKey)
	if !ok {
		return fmt.Errorf("unexpected public key type %T, want *rsa.PublicKey", pubAny)
	}

	// Wrap the KWP key using the import job key.
	wrappedWrappingKey, err := rsa.EncryptOAEP(sha1.New(), rand.Reader, pub, kwpKey, nil)
	if err != nil {
		return fmt.Errorf("failed to wrap KWP key: %w", err)
	}

	// Concatenate the wrapped KWP key and the wrapped target key.
	combined := append(wrappedWrappingKey, wrappedTarget...)

	// Build the request.
	req := &kmspb.ImportCryptoKeyVersionRequest{
		Parent:     cryptoKeyName,
		ImportJob:  importJobName,
		Algorithm:  kmspb.CryptoKeyVersion_EC_SIGN_P256_SHA256,
		WrappedKey: combined,
	}

	// Call the API.
	result, err := client.ImportCryptoKeyVersion(ctx, req)
	if err != nil {
		return fmt.Errorf("failed to import crypto key version: %w", err)
	}
	fmt.Fprintf(w, "Created crypto key version: %s\n", result.Name)
	return nil
}

Java

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

import com.google.cloud.kms.v1.CryptoKeyName;
import com.google.cloud.kms.v1.CryptoKeyVersion;
import com.google.cloud.kms.v1.ImportCryptoKeyVersionRequest;
import com.google.cloud.kms.v1.ImportJob;
import com.google.cloud.kms.v1.ImportJobName;
import com.google.cloud.kms.v1.KeyManagementServiceClient;
import com.google.crypto.tink.subtle.Kwp;
import com.google.protobuf.ByteString;
import java.io.IOException;
import java.security.GeneralSecurityException;
import java.security.KeyFactory;
import java.security.KeyPair;
import java.security.KeyPairGenerator;
import java.security.PublicKey;
import java.security.SecureRandom;
import java.security.spec.ECGenParameterSpec;
import java.security.spec.MGF1ParameterSpec;
import java.security.spec.X509EncodedKeySpec;
import java.util.Base64;
import javax.crypto.Cipher;
import javax.crypto.spec.OAEPParameterSpec;
import javax.crypto.spec.PSource;

public class ImportManuallyWrappedKey {

  public void importManuallyWrappedKey() throws GeneralSecurityException, 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 importJobId = "my-import-job";
    importManuallyWrappedKey(projectId, locationId, keyRingId, cryptoKeyId, importJobId);
  }

  // Generates and imports local key material into Cloud KMS.
  public void importManuallyWrappedKey(
      String projectId, String locationId, String keyRingId, String cryptoKeyId, String importJobId)
      throws GeneralSecurityException, IOException {

    // Generate a new ECDSA keypair, and format the private key as PKCS #8 DER.
    KeyPairGenerator generator = KeyPairGenerator.getInstance("EC");
    generator.initialize(new ECGenParameterSpec("secp256r1"));
    KeyPair kp = generator.generateKeyPair();
    byte[] privateBytes = kp.getPrivate().getEncoded();

    // 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 crypto key and import job names from the project, location,
      // key ring, and ID.
      final CryptoKeyName cryptoKeyName =
          CryptoKeyName.of(projectId, locationId, keyRingId, cryptoKeyId);
      final ImportJobName importJobName =
          ImportJobName.of(projectId, locationId, keyRingId, importJobId);

      // Generate a temporary 32-byte key for AES-KWP and wrap the key material.
      byte[] kwpKey = new byte[32];
      new SecureRandom().nextBytes(kwpKey);
      Kwp kwp = new Kwp(kwpKey);
      final byte[] wrappedTargetKey = kwp.wrap(privateBytes);

      // Retrieve the public key from the import job.
      ImportJob importJob = client.getImportJob(importJobName);
      String publicKeyStr = importJob.getPublicKey().getPem();
      // Manually convert PEM to DER. :-(
      publicKeyStr = publicKeyStr.replace("-----BEGIN PUBLIC KEY-----", "");
      publicKeyStr = publicKeyStr.replace("-----END PUBLIC KEY-----", "");
      publicKeyStr = publicKeyStr.replaceAll("\n", "");
      byte[] publicKeyBytes = Base64.getDecoder().decode(publicKeyStr);
      PublicKey publicKey =
          KeyFactory.getInstance("RSA").generatePublic(new X509EncodedKeySpec(publicKeyBytes));

      // Wrap the KWP key using the import job key.
      Cipher cipher = Cipher.getInstance("RSA/ECB/OAEPWithSHA-1AndMGF1Padding");
      cipher.init(
          Cipher.ENCRYPT_MODE,
          publicKey,
          new OAEPParameterSpec(
              "SHA-1", "MGF1", MGF1ParameterSpec.SHA1, PSource.PSpecified.DEFAULT));
      byte[] wrappedWrappingKey = cipher.doFinal(kwpKey);

      // Concatenate the wrapped KWP key and the wrapped target key.
      ByteString combinedWrappedKeys =
          ByteString.copyFrom(wrappedWrappingKey).concat(ByteString.copyFrom(wrappedTargetKey));

      // Import the wrapped key material.
      CryptoKeyVersion version =
          client.importCryptoKeyVersion(
              ImportCryptoKeyVersionRequest.newBuilder()
                  .setParent(cryptoKeyName.toString())
                  .setImportJob(importJobName.toString())
                  .setAlgorithm(CryptoKeyVersion.CryptoKeyVersionAlgorithm.EC_SIGN_P256_SHA256)
                  .setRsaAesWrappedKey(combinedWrappedKeys)
                  .build());

      System.out.printf("Imported: %s%n", version.getName());
    }
  }
}

Node.js

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

//
// 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 importJobId = 'my-import-job';

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

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

// Build the crypto key and importjob resource names
const cryptoKeyName = client.cryptoKeyPath(
  projectId,
  locationId,
  keyRingId,
  cryptoKeyId
);
const importJobName = client.importJobPath(
  projectId,
  locationId,
  keyRingId,
  importJobId
);

async function wrapAndImportKey() {
  // Generate a 32-byte key to import.
  const crypto = require('crypto');
  const targetKey = crypto.randomBytes(32);

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

  // Wrap the target key using the import job key
  const wrappedTargetKey = crypto.publicEncrypt(
    {
      key: importJob.publicKey.pem,
      oaepHash: 'sha256',
      padding: crypto.constants.RSA_PKCS1_OAEP_PADDING,
    },
    targetKey
  );

  // Import the target key version
  const [version] = await client.importCryptoKeyVersion({
    parent: cryptoKeyName,
    importJob: importJobName,
    algorithm: 'GOOGLE_SYMMETRIC_ENCRYPTION',
    wrappedKey: wrappedTargetKey,
  });

  console.log(`Imported key version: ${version.name}`);
  return version;
}

return wrapAndImportKey();

Python

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

import os

# Import the client library and Python standard cryptographic libraries.
from cryptography.hazmat import backends
from cryptography.hazmat.primitives import hashes
from cryptography.hazmat.primitives import keywrap
from cryptography.hazmat.primitives import serialization
from cryptography.hazmat.primitives.asymmetric import ec
from cryptography.hazmat.primitives.asymmetric import padding
from google.cloud import kms


def import_manually_wrapped_key(
    project_id: str,
    location_id: str,
    key_ring_id: str,
    crypto_key_id: str,
    import_job_id: str,
) -> None:
    """
    Generates and imports local key material to 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').
        crypto_key_id (string): ID of the key to import (e.g. 'my-asymmetric-signing-key').
        import_job_id (string): ID of the import job (e.g. 'my-import-job').
    """

    # Generate some key material in Python and format it in PKCS #8 DER as
    # required by Google Cloud KMS.
    key = ec.generate_private_key(ec.SECP256R1, backends.default_backend())
    formatted_key = key.private_bytes(
        serialization.Encoding.DER,
        serialization.PrivateFormat.PKCS8,
        serialization.NoEncryption(),
    )

    print(f"Generated key bytes: {formatted_key!r}")

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

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

    # Generate a temporary 32-byte key for AES-KWP and wrap the key material.
    kwp_key = os.urandom(32)
    wrapped_target_key = keywrap.aes_key_wrap_with_padding(
        kwp_key, formatted_key, backends.default_backend()
    )

    # Retrieve the public key from the import job.
    import_job = client.get_import_job(name=import_job_name)
    import_job_pub = serialization.load_pem_public_key(
        bytes(import_job.public_key.pem, "UTF-8"), backends.default_backend()
    )

    # Wrap the KWP key using the import job key.
    wrapped_kwp_key = import_job_pub.encrypt(
        kwp_key,
        padding.OAEP(
            mgf=padding.MGF1(algorithm=hashes.SHA1()),
            algorithm=hashes.SHA1(),
            label=None,
        ),
    )

    # Import the wrapped key material.
    client.import_crypto_key_version(
        {
            "parent": crypto_key_name,
            "import_job": import_job_name,
            "algorithm": kms.CryptoKeyVersion.CryptoKeyVersionAlgorithm.EC_SIGN_P256_SHA256,
            "rsa_aes_wrapped_key": wrapped_kwp_key + wrapped_target_key,
        }
    )

    print(f"Imported: {import_job.name}")

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.import para importar uma chave.

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_ID", "algorithm": "ALGORITHM", "wrappedKey": "WRAPPED_KEY"}'

Substitua o seguinte:

• IMPORT_JOB_ID: o nome completo do recurso da tarefa de importação correspondente.

• ALGORITHM: o algorithm da chave que está a ser importada, que é do tipo CryptoKeyVersionAlgorithm.

• WRAPPED_KEY: a chave envolvida manualmente no formato base64.

O pedido de importação de chaves é iniciado. Pode monitorizar o respetivo estado.

Verifique o estado da versão da chave importada

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

Pode verificar o estado de um pedido de importação através da CLI Google Cloud, da Google Cloud consola ou da API Cloud Key Management Service.

Consola

1. Abra a página Gestão de chaves na Google Cloud consola.

2. Clique no nome do conjunto de chaves que contém a tarefa de importação.

3. Clique no separador Tarefas de importação na parte superior da página.

4. O estado é visível em Estado junto ao nome da tarefa de importação.

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.

Use o comando versions list para verificar o estado. Use a mesma localização, conjunto de chaves de destino e chave de destino que criou anteriormente neste tópico.

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

Go

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

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 este código, primeiro configure um ambiente de desenvolvimento Java e instale o SDK Java do Cloud KMS.

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 este código, primeiro configure um ambiente de desenvolvimento do Node.js e instale o SDK do Node.js do Cloud KMS.

//
// 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 este código, primeiro configure um ambiente de desenvolvimento Python e instale o SDK Python do Cloud KMS.

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 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.

Chame o método ImportJob.get e verifique o campo state. Se o valor for state, significa que a tarefa de importação ainda está a ser criada.PENDING_GENERATION Verifique novamente o estado periodicamente até que seja ACTIVE.

Após a importação da versão inicial da chave, o estado da chave muda para Ativo. Para chaves simétricas, tem de definir a versão da chave importada como a versão principal antes de poder usar a chave.

Chaves simétricas: defina a versão principal

Este passo é necessário quando importa chaves simétricas e não é relevante para chaves assimétricas. Uma chave assimétrica não tem uma versão principal. Tem de usar a Google Cloud CLI para definir a versão principal.

Sugestão: normalmente, KEY_VERSION é 1, porque a versão importada é a primeira versão da chave.

gcloud kms keys set-primary-version KEY_NAME\
    --location=LOCATION\
    --keyring=KEY_RING\
    --version=KEY_VERSION

Reimporte uma chave destruída anteriormente

O Cloud Key Management Service suporta a reimportação de chaves, o que lhe permite restaurar uma versão de chave importada anteriormente no estado DESTROYED ou IMPORT_FAILED para o estado ENABLED, fornecendo o material de chave original. Se nunca tiver sido importado material de chave original devido a uma falha de importação inicial, pode ser fornecido qualquer material de chave.

Restrições

• Só é possível reimportar CryptoKeyVersions importados anteriormente.
• O material da chave reimportado tem de corresponder exatamente ao material da chave original se a versão tiver sido importada com êxito anteriormente.
• Não é possível reimportar os CryptoKeyVersions destruídos antes do lançamento desta funcionalidade. O campo reimport_eligible do elemento CryptoKeyVersion é true se a versão for elegível para reimportação e false se não for.

As chaves de software e HSM na nuvem podem ser reimportadas, mas as chaves externas não podem ser reimportadas.

Reimportar uma chave destruída

Crie um ImportJob para reimportação seguindo os passos em Crie a tarefa de importação. Pode usar um cartão existente ImportJob ou um novo ImportJob, desde que o nível de proteção corresponda ao nível de proteção original.

Consola

1. Aceda à página Gestão de chaves na Google Cloud consola.

   Aceda à página de gestão de chaves

2. Clique no nome do conjunto de chaves que contém a chave cuja versão da chave vai reimportar.

3. Clique na chave cuja versão da chave quer reimportar.

4. Clique nos três pontos junto à versão da chave que quer voltar a importar.

5. Selecione Reimportar versão da chave

6. Selecione a tarefa de importação no menu pendente Selecionar tarefa de importação.

7. No seletor Carregue a chave envolvida, selecione a chave que já envolveu. Esta chave tem de corresponder ao material da chave original.

8. Clique em Reimportar.

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.

1. Reimporte a versão da chave através do material da chave original.

   gcloud kms keys versions import \
   --location LOCATION \
   --keyring KEY_RING \
   --key KEY_NAME \
   --version KEY_VERSION \
   --algorithm ALGORITHM \
   --import-job IMPORT_JOB \
   --target-key-file PATH_TO_KEY \
   

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.

1. No corpo do pedido do método cryptoKeyVersions.import, defina o campo cryptoKeyVersion com o nome da versão da chave da versão que está a ser importada. Tem de ser um elemento subordinado da chave criptográfica.

2. No corpo do pedido, defina o campo algorithm para o algoritmo da chave que está a ser importada. Este valor tem de corresponder ao algoritmo da versão da chave original. O campo algorithm é do tipo CryptoKeyVersionAlgorithm.

3. No corpo do pedido, defina o campo wrappedKeyMaterial para o material da chave que já encapsulou.

4. Chame o método cryptoKeyVersions.import. A resposta cryptoKeyVersions.import é do tipo CryptoKeyVersion. Quando uma chave é importada com êxito, o respetivo estado é ENABLED e pode usá-la no Cloud KMS.

O que se segue?

• Valide uma chave importada. Depois de confirmar que o material da chave importado é idêntico à chave original, pode usar a chave para assinar ou proteger dados.
• Resolva problemas de uma importação de chaves falhada.