Importar uma versão de chave para o Cloud KMS

Neste tópico, mostramos como importar uma chave criptográfica para o Cloud HSM ou Cloud Key Management Service como uma nova versão de chave.

Para mais detalhes sobre como importar chaves, incluindo limitações e restrições, consulte Importação de chave.

Você pode concluir as etapas deste tópico em 5 a 10 minutos, sem incluir as etapas Antes de começar. Encapsular a chave manualmente aumenta a complexidade da tarefa.

Antes de começar

Recomendamos que você crie um novo projeto para testar esse recurso, para facilitar a limpeza após o teste e garantir que você tenha as permissões adequadas do Identity and Access Management (IAM) para importar uma chave.

Antes de importar uma chave, você precisa preparar o projeto, o sistema local e a própria chave.

Como preparar o projeto

  1. Faça login na sua conta do Google Cloud. Se você começou a usar o Google Cloud agora, 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.

  2. No console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.

    Acessar o seletor de projetos

  3. Verifique se a cobrança está ativada para o seu projeto do Google Cloud.

  4. Ative a API necessária.

    Ative a API

  5. Instale a CLI do Google Cloud.

  6. Para inicializar a CLI gcloud, execute o seguinte comando: 

    gcloud init
    7.

  7. No console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.

    Acessar o seletor de projetos

  8. Verifique se a cobrança está ativada para o seu projeto do Google Cloud.

  9. Ative a API necessária.

    Ative a API

  10. Instale a CLI do Google Cloud.

  11. Para inicializar a CLI gcloud, execute o seguinte comando: 

    gcloud init
    12.

  12. O usuário que está executando a importação precisa das seguintes permissões do IAM para criar keyrings, chaves e jobs de importação. Se o usuário não for o proprietário do projeto, será possível atribuir a ele os dois papéis predefinidos a seguir:

    • roles/editor
    • roles/cloudkms.importer

    Para mais informações sobre os papéis e as permissões do IAM disponíveis para o Cloud KMS, consulte Permissões e papéis.

Como preparar o sistema local

Prepare o sistema local escolhendo uma das opções a seguir. O encapsulamento automático de chaves é recomendado para a maioria dos usuários.

Como preparar a chave

Verifique se o algoritmo e o comprimento da chave são compatíveis. Os algoritmos permitidos para uma chave dependem se ela é usada para criptografia simétrica, criptografia assimétrica ou assinatura assimétrica, bem como se a chave está armazenada em software ou em um HSM. Você especifica o algoritmo da chave como parte da solicitação de importação.

Separadamente, você também precisa verificar como a chave está codificada e fazer ajustes, se necessário.

Os seguintes itens não podem ser alterados para uma versão de chave depois que ela é criada ou importada:

  • O nível de proteção indica se a chave persiste no software, em um HSM ou em um sistema de gerenciamento de chaves externo. Não é possível mover o material da chave de um desses ambientes de armazenamento para outro. Todas as versões de uma chave têm o mesmo nível de proteção.

  • A purpose indica se as versões da chave são usadas para criptografia simétrica, assimétrica ou assinatura assimétrica. A finalidade da chave limita os possíveis algoritmos que podem ser usados para criar versões dela. Todas as versões de uma chave têm a mesma finalidade.

Se você não tiver uma chave para importar, mas quiser validar o procedimento para importação de chaves, crie uma chave simétrica no sistema local usando o seguinte comando:

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

Use esta chave somente para teste. Uma chave criada dessa maneira pode não ser apropriada para uso em produção.

Se você precisar encapsular a chave manualmente, faça isso antes de continuar com os procedimentos deste tópico.

Criar a chave e o keyring de segmentação

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

Quando você importa uma chave para o Cloud KMS ou o Cloud HSM, a chave importada se torna uma nova versão de chave em uma chave atual do Cloud KMS ou do Cloud HSM. No restante deste tópico, essa chave é chamada de chave de segmentação. A chave de segmentação já precisa existir para que seja possível importar o material da chave para ela.

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

Como opção, é possível especificar que a chave recém-criada contenha apenas versões importadas, o que impede a geração acidental de novas versões no Cloud KMS.

Uma chave existe em um keyring. Neste tópico, esse keyring é chamado de keyring de segmentação. O local do keyring de segmentação determina o local em que o material da chave estará disponível após a importação. Não é possível criar ou importar chaves do Cloud HSM em alguns locais. Depois que uma chave é criada, ela não pode ser movida para um keyring ou local diferente.

Siga estas etapas para criar uma chave vazia em um novo keyring usando a Google Cloud CLI ou o console do 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 de local 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. Para o nível de proteção, selecione Software ou HSM e clique em Continuar.

  8. Em Material da chave, selecione Chave importada e clique em Continuar. Isso impede a criação de uma versão inicial da chave.

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

  10. Opcional: se você quiser que a chave contenha apenas versões de chave importadas, selecione Restringir versões da chave para importar apenas. Isso evita que você crie acidentalmente novas versões de chave no Cloud KMS.

  11. Opcional: para chaves importadas, a rotação automática está desativada por padrão. Para ativar a rotação 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. Se você pretende importar para uma chave do Cloud HSM, selecione um local compatível com o Cloud HSM.

    gcloud kms keyrings create KEY_RING \
  --location LOCATION

    Saiba mais sobre como criar keyring.

  2. Crie a chave de segmentação.

    • Especifique o objetivo da chave.
    • Impeça que uma versão inicial seja criada usando a sinalização --skip-initial-version-creation.
    • Opcional: evite que novas versões sejam criadas no Cloud KMS usando a sinalização --import-only.
    • Opcional: não especifique uma política de rotação. 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. Não é possível especificar uma política de rotação se você tiver especificado a sinalização --import-only.
    gcloud kms keys create KEY_NAME \
  --location LOCATION \
  --keyring KEY_RING \
  --purpose PURPOSE \
  --skip-initial-version-creation \
  --import-only

    Saiba mais sobre como criar chaves do Cloud KMS ou chaves do Cloud HSM.

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

// 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 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.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 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 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 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 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,
        }
    )
    print(f"Created hsm key: {created_key.name}")

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 somente 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 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 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 esse job de importação residirão no software, em um HSM ou em um sistema de gerenciamento de chaves externo. O nível de proteção não pode ser alterado depois que a chave for 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 de destino do Google Cloud. É possível escolher uma chave RSA de 3072 bits ou 4096 bits. A menos que você tenha requisitos específicos, é recomendável usar a chave de encapsulamento de 3072 bits.

É possível criar um job de importação usando a CLI gcloud, o console do Google 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 de destino.

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

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

  5. No campo Nome, digite o nome do job de importação.

  6. Na lista suspensa 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 comando, primeiro instale ou faça upgrade para a versão mais recente da Google Cloud CLI.

Use um comando como o seguinte para criar um job 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 keyring e local da chave de segmentação.
  • Defina o nível de proteção como software ou hsm.
  • Defina o método de importação como 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 ou rsa-oaep-4096-sha256.

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

// 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 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.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 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 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 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 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 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 criar um job 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:

Como 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 console do Google 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á assim:

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.

Como impedir a modificação de jobs de importação

O job de importação determina muitas características da chave importada, incluindo o algoritmo da chave e se uma chave importada é uma chave HSM ou uma chave de software. É possível configurar permissões do IAM para impedir que os usuários criem jobs de importação e, ao mesmo tempo, permitir que eles usem jobs de importação para importar chaves.

  1. Conceda a permissão importjobs.create apenas aos administradores de chaves.
  2. Conceda a permissão importjobs.useToImport para um job de importação específico ao operador que usará esse job para importar chaves.
  3. Ao criar o job de importação, especifique o nível de proteção e o algoritmo para as versões de chave importadas usando o job.

Até que o job de importação expire, os usuários que têm a permissão importjobs.useToImport e não têm a permissão importjobs.create para um determinado job de importação podem importar chaves, mas não podem modificar as características do job de importação.

Importar a chave

Depois de verificar o status do job de importação, você pode fazer uma solicitação de importação.

É possível usar sinalizações diferentes para fazer a solicitação de importação, dependendo se você quer que a Google Cloud CLI encapsule sua chave automaticamente ou se você já encapsulou sua chave manualmente.

Independentemente de você encapsular a chave de maneira manual ou automática, é necessário definir o algoritmo como um algoritmo compatível que corresponda ao comprimento da chave real a ser importada e que especifique a finalidade da chave.

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

  • As chaves com finalidade ASYMMETRIC_DECRYPT ou ASYMMETRIC_SIGN são compatíveis com diversos algoritmos e comprimentos.

    Não é possível alterar a finalidade de uma chave depois que ela é criada. No entanto, as versões de chave subsequentes podem ser criadas com comprimentos diferentes em relação à versão inicial da chave.

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

Para usar o encapsulamento automático, use a Google Cloud CLI. Use um comando como o seguinte. Defina --target-key-file como o local da chave desencapsulada a ser unida e importada. Não defina --wrapped-key-file.

Como opção, você pode definir a sinalização --public-key-file como o local em que já foi feito o download da chave pública. Importar um grande número de chaves impede o download da chave pública durante cada importação. Por exemplo, você pode escrever um script que fez o download da chave pública uma vez e forneceu o local 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 é encapsulada pela chave de encapsulamento associada ao job de importação, transmitida ao Google Cloud e importada como uma nova versão de chave na chave de segmentação.

Como importar uma chave com quebra automática manual

Use as instruções nesta seção para importar uma chave que você encapsulou manualmente. Defina --wrapped-key-file ao local da chave que você encapsulou manualmente. Não defina --target-key-file.

Como opção, você pode definir a sinalização --public-key-file como o local em que já foi feito o download da chave pública. Importar um grande número de chaves impede o download da chave pública durante cada importação. Por exemplo, você pode escrever um script que fez o download da chave pública uma vez e forneceu o local ao importar cada chave.

Console

  1. Abra a página Gerenciamento de chaves no Console do Google Cloud.

  2. Clique no nome do keyring que contém o job de importação. A chave de destino é mostrada, juntamente com todas as outras chaves do keyring.

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

  4. Selecione seu job de importação no menu suspenso Selecionar tarefa de importação.

  5. No seletor Fazer upload da chave encapsulada, selecione a chave que você já encapsulou.

  6. Se você estiver importando uma chave assimétrica, selecione o algoritmo no menu suspenso Algoritmo. A página Importar versão da chave será semelhante a:

    Importar versão da chave

  7. Clique em Importar.

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 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 a saída do comando gcloud kms keys versions import --help.

Go

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

import (
	"context"
	"crypto/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 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.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 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 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 esse código, primeiro configure um ambiente de desenvolvimento Python e instale o SDK do Cloud KMS para Python.

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 curl como um cliente HTTP para demonstrar o uso da API. Para mais informações sobre controle de acesso, consulte Como acessar a API Cloud KMS.

Use o método cryptoKeyVersions.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:

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

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

  • WRAPPED_KEY: a chave encapsulada manualmente no formato base64.

A solicitação de importação de chave é iniciada. Você pode monitorar o status.

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 com sucesso. 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 do Google Cloud ou a API Cloud Key Management Service.

Console

  1. Abra a página Gerenciamento de chaves no Console do Google 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. 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 da chave muda para Ativo. Para chaves simétricas, é necessário definir a versão da chave importada como a principal antes de usar a chave.

Chaves simétricas: definir a versão principal

Esta etapa é obrigatória ao importar chaves simétricas e não é relevante para chaves assimétricas. Uma chave assimétrica não tem uma versão principal. É necessário usar a Google Cloud CLI para definir a versão principal.

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

Importar novamente uma chave destruída anteriormente

O Cloud Key Management Service oferece suporte à reimportação de chaves, o que permite restaurar uma versão de chave importada anteriormente no estado DESTROYED ou IMPORT_FAILED para o estado ENABLED, fornecendo o material da chave original. Se nenhum material de chave original tiver sido importado devido a uma falha na importação, qualquer material de chave poderá ser fornecido.

Restrições

  • Apenas CryptoKeyVersions importados anteriormente podem ser importados novamente.
  • O material da chave importada precisa corresponder ao material original da chave exatamente se ela tiver sido importada anteriormente.
  • CryptoKeyVersions destruídos antes do lançamento desse recurso não podem ser importados novamente. O campo reimport_eligible do CryptoKeyVersion será true se a versão se qualificar para reimportação e false se não estiver.

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

Como importar novamente uma chave destruída

Crie um ImportJob para importar novamente seguindo as etapas em Criar o job de importação. Você pode usar um ImportJob existente ou um novo ImportJob, desde que o nível de proteção corresponda ao nível de proteção original.

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 a chave com a versão que você importará novamente.

  3. Clique na chave com a versão que você quer importar novamente.

  4. Clique nos três pontos ao lado da versão da chave que você quer importar novamente.

  5. Selecione Reimportar versão de chave.

  6. Selecione seu job de importação no menu suspenso Selecionar tarefa de importação.

  7. No seletor Fazer upload da chave encapsulada, selecione a chave que você já encapsulou. A chave precisa corresponder ao material original.

  8. Clique em Importar novamente.

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. Importe novamente a versão da chave usando o material original da chave.

    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 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. No corpo da solicitação do método cryptoKeyVersions.import, defina o campo cryptoKeyVersion como o nome da versão da chave da versão que está sendo importada. Precisa ser um filho da chave de criptografia.

  2. No corpo da solicitação, defina o campo algorithm como o algoritmo da chave que está sendo importada. Esse valor precisa corresponder ao algoritmo da versão original da chave. O campo algorithm é do tipo CryptoKeyVersionAlgorithm.

  3. No corpo da solicitação, defina o campo wrappedKeyMaterial para o material da chave que você já encapsulado.

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

A seguir

Anterior
Configurar o encapsulamento automático de chaves
Próxima
Verificar uma versão de chave importada