Google utiliza tecnología de IA para traducir contenido a tu idioma preferido. Las traducciones realizadas con IA pueden contener errores.

Importa una versión de clave a Cloud KMS

En esta guía, se muestra cómo importar una clave criptográfica a Cloud HSM o Cloud Key Management Service como una versión de clave nueva.

Para obtener más detalles sobre la importación de claves, incluidas las limitaciones y restricciones, consulta Importación de claves.

Puedes completar los pasos de esta guía en un plazo de 5 a 10 minutos, sin incluir los pasos de la sección Antes de comenzar. Unir la clave de forma manual agrega complejidad a la tarea.

Antes de comenzar

Te recomendamos que crees un proyecto nuevo para probar esta función, de modo que sea más fácil limpiar los datos después de la prueba y asegurarte de tener los permisos adecuados de Identity and Access Management (IAM) para importar una clave.

Antes de importar una clave, debes preparar el proyecto, el sistema local y la clave.

Prepara el proyecto

Accede a tu cuenta de Google Cloud . Si es la primera vez que usas Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.

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.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the required API, if it is not already enabled.

Roles required to enable APIs

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

Enable the API

Install the Google Cloud CLI.

If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

To initialize the gcloud CLI, run the following command:

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.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the required API, if it is not already enabled.

Roles required to enable APIs

Enable the API

Install the Google Cloud CLI.

If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

To initialize the gcloud CLI, run the following command:

gcloud init

El usuario que realiza la importación necesita los siguientes permisos de IAM para crear claves, llaveros de claves y trabajos de importación. Si el usuario no es el propietario del proyecto, puedes asignarle ambos roles predefinidos:
- roles/editor
- roles/cloudkms.importer
Para obtener más información sobre los roles y permisos de IAM disponibles para Cloud KMS, consulta Permisos y roles.

Prepara el sistema local

Para preparar el sistema local, elige una de las siguientes opciones. Se recomienda el empaquetado automático de claves para la mayoría de los usuarios.

Si deseas permitir que Google Cloud CLI una tus claves de forma automática antes de transmitirlas a Google Cloud, debes instalar la biblioteca de criptografía de Pyca en tu sistema local. El trabajo de importación que encapsula y protege la clave de forma local antes de enviarla a Google Cloudusa la biblioteca de Pyca.
Si deseas envolver tus claves de forma manual, debes configurar OpenSSL para el envoltorio manual de claves.

Prepara la clave

Verifica que el algoritmo y la longitud de tu clave sean compatibles. Los algoritmos permitidos para una clave dependen de si esta se usa para la encriptación simétrica, la criptografía asimétrica o la firma asimétrica, y de si se almacena en un software o en un HSM. Especifica el algoritmo de la clave como parte de la solicitud de importación.

Por separado, también debes verificar cómo se codifica la clave y realizar los ajustes necesarios.

No se puede cambiar lo siguiente para una versión de clave después de que se crea o importa:

El nivel de protección indica si la clave persiste en el software, en un HSM de múltiples arrendatarios, en un HSM de un solo arrendatario o en un sistema externo de administración de claves. El material de la clave no se puede mover de uno de estos entornos de almacenamiento a otro. Todas las versiones de una clave tienen el mismo nivel de protección.
El propósito indica si las versiones de la clave se usan para la encriptación simétrica, la criptografía asimétrica o la firma asimétrica. El propósito de la clave limita los posibles algoritmos que se pueden usar para crear versiones de esa clave. Todas las versiones de una clave tienen el mismo propósito.

Si no tienes una clave que desees importar, pero quieres validar el procedimiento de importación de claves, puedes crear una clave simétrica en el sistema local con el siguiente comando:

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

Usa esta clave solo para realizar pruebas. Es posible que una clave creada de esta manera no sea adecuada para su uso en producción.

Si necesitas ajustar la llave de forma manual, hazlo antes de continuar con los procedimientos de esta guía.

Crea la clave de segmentación y el llavero de claves

Una clave de Cloud KMS es un objeto contenedor que contiene cero o más versiones de clave. Cada versión de la clave contiene una clave criptográfica.

Cuando importas una clave a Cloud KMS o Cloud HSM, la clave importada se convierte en una versión de clave nueva en una clave existente de Cloud KMS o Cloud HSM. En el resto de esta guía, esta clave se denomina clave de segmentación. La clave de destino debe existir antes de que puedas importar material de clave a ella.

La importación de una versión de clave no afecta las versiones existentes de esa clave. Sin embargo, se recomienda crear una clave vacía cuando se prueba la importación de claves. Una clave vacía no tiene versión, no está activa y no se puede usar.

De manera opcional, puedes especificar que la clave recién creada solo contenga versiones importadas, lo que evita la generación accidental de versiones nuevas en Cloud KMS.

Existe una clave en un llavero de claves; en esta guía, este llavero de claves se denomina llavero de claves de destino. La ubicación del llavero de claves de destino determina la ubicación en la que el material de la clave estará disponible después de la importación. Las claves de Cloud HSM no se pueden crear ni importar en algunas ubicaciones. Después de crear una llave, no se puede mover a otro llavero de claves o ubicación.

Sigue estos pasos para crear una clave vacía en un llavero nuevo con Google Cloud CLI o la consola de Google Cloud .

Console

En la consola de Google Cloud , ve a la página Administración de claves.

Ir a Key Management
Haz clic en Crear llavero de claves.
En el campo Nombre del llavero de claves, ingresa el nombre de tu llavero de claves.
En Tipo de ubicación, selecciona un tipo de ubicación y una ubicación.
Haz clic en Crear. Se abre la página Crear clave.
En el campo Nombre de la clave, ingresa el nombre de la clave.
En Nivel de protección, selecciona Software, HSM o HSM de un solo arrendatario.
Si seleccionaste HSM de usuario único, selecciona la instancia de HSM de usuario único en la que deseas crear la clave.
En Material de clave, selecciona Clave importada y, luego, haz clic en Continuar. Esto evita que se cree una versión de clave inicial.
Establece el Propósito y el Algoritmo de la clave y, luego, haz clic en Continuar.
Opcional: Si quieres que esta clave contenga solo versiones de claves importadas, selecciona Restringe las versiones de claves solo para la importación. Esto evita que crees accidentalmente versiones de claves nuevas en Cloud KMS.
Opcional: En el caso de las claves importadas, la rotación automática está inhabilitada de forma predeterminada. Para habilitar la rotación automática, selecciona un valor en el campo Período de rotación de claves.

Si habilitas la rotación automática, se generarán versiones de claves nuevas en Cloud KMS, y la versión de la clave importada ya no será la versión predeterminada después de una rotación.
Haz clic en Crear.

gcloud

Para usar Cloud KMS en la línea de comandos, primero instala o actualiza a la versión más reciente de Google Cloud CLI.

Crea el llavero de claves de destino. Elige una ubicación que sea compatible con el nivel de protección que deseas usar. Para obtener más información sobre las ubicaciones compatibles, consulta Ubicaciones de Cloud KMS.
```
gcloud kms keyrings create KEY_RING \
  --location LOCATION
```
Puedes obtener más información para crear llaveros de claves.
Crea la clave de destino con el comando kms keys create y la marca --skip-initial-version-creation. De esta manera, se crea una clave sin versión inicial, por lo que el material de la clave que importes será la versión 1. Usa la marca --import-only para evitar que Cloud KMS genere material de clave para las versiones de clave nuevas. Con este parámetro de configuración establecido, se deben importar las versiones de claves nuevas para esta clave. Las claves creadas como --import-only se deben rotar de forma manual.
```
gcloud kms keys create KEY_NAME \
  --location LOCATION \
  --keyring KEY_RING \
  --purpose PURPOSE \
  --protection-level PROTECTION_LEVEL \
  --skip-initial-version-creation \
  --import-only
```
Reemplaza lo siguiente:
- KEY_NAME: Es el nombre que deseas usar para la clave.
- LOCATION: Es la ubicación del llavero de claves.
- KEY_RING: Es el llavero de claves en el que deseas crear la clave.
- PURPOSE: Es el propósito que deseas usar para la clave.
- PROTECTION_LEVEL: Es el nivel de protección que deseas usar para la clave, por ejemplo, HSM.
Para crear una clave de Cloud HSM de usuario único, agrega la marca --cryptoKeyBackend a este comando y agrega el identificador de recurso de la instancia de Cloud HSM de usuario único en la que deseas importar la clave:
```
--crypto-key-backend="projects/INSTANCE_PROJECT/locations/LOCATION/singleTenantHsmInstances/INSTANCE_NAME"
```

Go

Para ejecutar este código, primero configura un entorno de desarrollo de Go y, luego, instala el SDK de Go para 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 ejecutar este código, primero configura un entorno de desarrollo de Java y, luego, instala el SDK de Java para 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 ejecutar este código, primero configura un entorno de desarrollo de Node.js y, luego, instala el SDK de Node.js para 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 ejecutar este código, primero configura un entorno de desarrollo de Python y, luego, instala el SDK de Python para 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

En estos ejemplos, se usa curl como un cliente HTTP para demostrar el uso de la API. Para obtener más información sobre el control de acceso, consulta Accede a la API de Cloud KMS.

Crea un llavero de claves nuevo:

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 "{}"

Consulta la documentación de la API de KeyRing.create para obtener más información.

Crea una clave vacía solo de importación:

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

Consulta la documentación de la API de CryptoKey.create para obtener más información.

Si deseas crear tu clave en un Cloud HSM de usuario único, agrega el campo cryptoKeyBackend al cuerpo del comando y agrega el identificador de recurso de la instancia de Cloud HSM de usuario único en la que deseas importar la clave:

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

El llavero de claves y la clave se crearon, pero la clave no contiene material, no tiene versión y no está activa. Luego, crea un trabajo de importación.

Crea el trabajo de importación

Un trabajo de importación define las características de las claves que importa, incluidas las propiedades que no se pueden cambiar después de importar la clave.

El nivel de protección define si las claves importadas por este trabajo de importación residirán en software, en un HSM de varios usuarios, en un HSM de un solo usuario o en un sistema de administración de claves externo. El nivel de protección no se puede cambiar después de que se importe la clave.

El método de importación define el algoritmo que se usa para crear la clave de unión que protege las claves importadas durante el tránsito desde tu sistema local hasta el proyecto Google Cloud de destino. Puedes elegir una clave RSA de 3072 bits o 4096 bits. A menos que tengas requisitos específicos, se recomienda la clave de unión de 3072 bits.

Puedes crear un trabajo de importación con gcloud CLI, la consola deGoogle Cloud o la API de Cloud Key Management Service.

Console

En la consola de Google Cloud , ve a la página Administración de claves.

Ir a Key Management
Haz clic en el nombre del llavero de claves de destino.
Establece el nivel de protección en Software, HSM o HSM de un solo arrendatario. Usa el mismo nivel de protección que estableciste para la clave de destino.
Haz clic en Crear trabajo de importación.
En el campo Nombre, ingresa el nombre de tu trabajo de importación.
En el menú desplegable Método de importación, configura el método de importación en RSA de 3072 bits o RSA de 4096 bits.
Haz clic en Crear.

gcloud

Para usar Cloud KMS en la línea de comandos, primero instala o actualiza a la versión más reciente de Google Cloud CLI.

Usa un comando como el siguiente para crear un trabajo de importación.

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

Usa el mismo llavero de claves y la misma ubicación que usa la clave de destino.
Establece el nivel de protección en el mismo valor que usaste para la clave de destino.
Configura el método de importación en uno de los siguientes valores:
- 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 ejecutar este código, primero configura un entorno de desarrollo de Go y, luego, instala el SDK de Go para 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 ejecutar este código, primero configura un entorno de desarrollo de Java y, luego, instala el SDK de Java para 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 ejecutar este código, primero configura un entorno de desarrollo de Node.js y, luego, instala el SDK de Node.js para 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 ejecutar este código, primero configura un entorno de desarrollo de Python y, luego, instala el SDK de Python para 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

En estos ejemplos, se usa curl como un cliente HTTP para demostrar el uso de la API. Para obtener más información sobre el control de acceso, consulta Accede a la API de Cloud KMS.

Para crear un trabajo de importación, usa el 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"}'

Reemplaza lo siguiente:

IMPORT_METHOD: Es un método de unión de claves compatible.
PROTECTION_LEVEL: Es el nivel de protección de las versiones de clave importadas por este trabajo de importación.

Verifica el estado del trabajo de importación

El estado inicial de un trabajo de importación es PENDING_GENERATION. Cuando el estado es ACTIVE, puedes usarlo para importar claves.

Un trabajo de importación vence después de tres días. Si el trabajo de importación venció, debes crear uno nuevo.

Puedes comprobar el estado de un trabajo de importación con Google Cloud CLI, la consola deGoogle Cloud o la API de Cloud Key Management Service.

Console

En la consola de Google Cloud , ve a la página Administración de claves.

Ir a Key Management
Haz clic en el nombre del llavero de claves que contiene tu trabajo de importación.
Haz clic en la pestaña Trabajos de importación en la parte superior de la página.
El estado aparecerá en Estado junto al nombre de tu trabajo de importación.

gcloud

Para usar Cloud KMS en la línea de comandos, primero instala o actualiza a la versión más reciente de Google Cloud CLI.

Cuando un trabajo de importación está activo, puedes usarlo para importar claves. Este proceso puede tardar unos minutos. Usa este comando para verificar que el trabajo de importación esté activo. Usa la ubicación y el llavero de claves en los que creaste el trabajo de importación.

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

El resultado es similar a lo siguiente:

state: ACTIVE

Go

Para ejecutar este código, primero configura un entorno de desarrollo de Go y, luego, instala el SDK de Go para 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 ejecutar este código, primero configura un entorno de desarrollo de Java y, luego, instala el SDK de Java para 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 ejecutar este código, primero configura un entorno de desarrollo de Node.js y, luego, instala el SDK de Node.js para 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 ejecutar este código, primero configura un entorno de desarrollo de Python y, luego, instala el SDK de Python para 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

En estos ejemplos, se usa curl como un cliente HTTP para demostrar el uso de la API. Para obtener más información sobre el control de acceso, consulta Accede a la API de Cloud KMS.

Para verificar el estado de un trabajo de importación, usa el 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"

En cuanto el trabajo de importación esté activo, podrás realizar una solicitud para importar una clave.

Cómo evitar la modificación de trabajos de importación

El trabajo de importación determina muchas características de la clave importada, incluido el algoritmo de la clave y si una clave importada es una de HSM o de software. Puedes configurar los permisos de IAM para evitar que los usuarios creen trabajos de importación, pero permitirles usar trabajos de importación para importar claves.

Otorga el permiso importjobs.create solo a los administradores clave.
Otorga el permiso importjobs.useToImport para un trabajo de importación específico al operador que usará ese trabajo a fin de importar claves.
Cuando crees el trabajo de importación, especifica el nivel de protección y el algoritmo para las versiones de claves importadas con él.

Hasta que el trabajo de importación caduque, los usuarios que tienen el permiso importjobs.useToImport y no tienen el permiso importjobs.create para un trabajo de importación determinado pueden importar claves, pero no pueden modificar las características del trabajo de importación.

Importa la clave

Después de verificar el estado del trabajo de importación, puedes realizar una solicitud de importación.

Usas diferentes marcas para realizar la solicitud de importación, según si deseas que Google Cloud CLI ajuste tu clave automáticamente o si ya ajustaste tu clave de forma manual.

Sin importar si uniste tu clave de forma manual o automática, debes configurar un algoritmo compatible que coincida con la longitud de la clave real que se importará y especifique el propósito de la clave.

Las claves con propósito ENCRYPT_DECRYPT usan el algoritmo google-symmetric-encryption y tienen una longitud de 32.
Las claves con el propósito ASYMMETRIC_DECRYPT o ASYMMETRIC_SIGN admiten una variedad de algoritmos y longitudes.

El propósito de la clave no se puede cambiar después de crearla, pero las versiones de la clave posteriores se pueden crear en longitudes diferentes a la versión inicial.

Importa y une una clave de forma automática

Si quieres usar el ajuste automático, debes usar Google Cloud CLI. Usa un comando como el siguiente. Establece --target-key-file en la ubicación de la clave sin envolver para envolverla e importarla. No establezcas --wrapped-key-file.

De manera opcional, puedes establecer la marca --public-key-file en la ubicación en la que ya se descargó la clave pública. Cuando se importa una gran cantidad de claves, esto evita que se descargue la clave pública durante cada importación. Por ejemplo, podrías escribir una secuencia de comandos que descargue la clave pública una vez y, luego, proporcione su ubicación cuando se importe cada clave.

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

La clave se une con la clave de unión asociada al trabajo de importación, se transmite a Google Cloudy se importa como una nueva versión de la clave de destino.

Importa una clave unida de forma manual

Usa las instrucciones de esta sección para importar una clave que uniste manualmente. Establece --wrapped-key-file en la ubicación de la clave que encapsulaste de forma manual. No establezcas --target-key-file.

Console

En la consola de Google Cloud , ve a la página Administración de claves.

Ir a Key Management
Haz clic en el nombre del llavero de claves que contiene tu trabajo de importación. Se mostrará la clave de destino junto con cualquier otra clave en el llavero de claves.
Haz clic en el nombre de la clave de segmentación y, luego, en Importar versión de clave.
Selecciona tu trabajo de importación en el menú desplegable Seleccionar trabajo de importación.
En el selector Subir la clave unida (Upload the wrapped key), selecciona la clave que ya uniste.
Si importas una clave asimétrica, selecciona el algoritmo en el menú desplegable Algoritmo. Tu página Importar versión de clave debe ser similar a la que se muestra a continuación:
Haz clic en Importar.

gcloud

Para usar Cloud KMS en la línea de comandos, primero instala o actualiza a la versión más reciente de Google Cloud CLI.

Usa un comando como el siguiente.

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 obtener más información, consulta el resultado del comando gcloud kms keys versions import --help.

Go

Para ejecutar este código, primero configura un entorno de desarrollo de Go y, luego, instala el SDK de Go para 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 ejecutar este código, primero configura un entorno de desarrollo de Java y, luego, instala el SDK de Java para 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 ejecutar este código, primero configura un entorno de desarrollo de Node.js y, luego, instala el SDK de Node.js para 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 ejecutar este código, primero configura un entorno de desarrollo de Python y, luego, instala el SDK de Python para 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

En estos ejemplos, se usa curl como un cliente HTTP para demostrar el uso de la API. Para obtener más información sobre el control de acceso, consulta Accede a la API de Cloud KMS.

Usa el método cryptoKeyVersions.import para importar una clave.

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"}'

Reemplaza lo siguiente:

IMPORT_JOB_ID: Es el nombre completo del recurso del trabajo de importación correspondiente.
ALGORITHM: Es el algorithm de la clave que se importa, que es de tipo CryptoKeyVersionAlgorithm.
WRAPPED_KEY: Es la clave ajustada manualmente en formato base64.

Se inicia la solicitud de importación de claves. Puedes supervisar su estado.

Verifica el estado de la versión de clave importada

El estado inicial de una versión de clave importada es PENDING_IMPORT. Cuando el estado es ENABLED, la versión de la clave se importó correctamente. Si falla la importación, el estado es IMPORT_FAILED.

Puedes comprobar el estado de una solicitud de importación con Google Cloud CLI, la consola deGoogle Cloud o la API de Cloud Key Management Service.

Console

En la consola de Google Cloud , ve a la página Administración de claves.

Ir a Key Management
Haz clic en el nombre del llavero de claves que contiene tu trabajo de importación.
Haz clic en la pestaña Trabajos de importación en la parte superior de la página.
El estado aparecerá en Estado junto al nombre de tu trabajo de importación.

gcloud

Para usar Cloud KMS en la línea de comandos, primero instala o actualiza a la versión más reciente de Google Cloud CLI.

Usa el comando versions list para verificar el estado. Usa la misma ubicación, el llavero de claves de destino y la clave de destino que creaste antes en este tema.

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

Go

Para ejecutar este código, primero configura un entorno de desarrollo de Go y, luego, instala el SDK de Go para 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 ejecutar este código, primero configura un entorno de desarrollo de Java y, luego, instala el SDK de Java para 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 ejecutar este código, primero configura un entorno de desarrollo de Node.js y, luego, instala el SDK de Node.js para 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 ejecutar este código, primero configura un entorno de desarrollo de Python y, luego, instala el SDK de Python para 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

En estos ejemplos, se usa curl como un cliente HTTP para demostrar el uso de la API. Para obtener más información sobre el control de acceso, consulta Accede a la API de Cloud KMS.

Llama al método ImportJob.get y verifica el campo state. Si state es PENDING_GENERATION, el trabajo de importación todavía se está creando. Vuelve a verificar periódicamente el estado hasta que sea ACTIVE.

Después de importar la versión inicial de la clave, el estado de la clave cambia a Activo. En el caso de las claves simétricas, debes establecer la versión de la clave importada como la versión principal antes de poder usar la clave.

Claves simétricas: Configura la versión principal

Este paso es obligatorio cuando se importan claves simétricas y no es relevante para las claves asimétricas. Una clave asimétrica no tiene una versión principal. Debes usar Google Cloud CLI para establecer la versión principal.

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

Vuelve a importar una clave destruida previamente

Cloud Key Management Service admite la reimportación de claves, lo que te permite restablecer una versión de clave importada anteriormente en estado DESTROYED o IMPORT_FAILED al estado ENABLED proporcionando el material de clave original. Si nunca se importó material de clave original debido a una falla en la importación inicial, se puede proporcionar cualquier material de clave.

Restricciones

Solo se pueden volver a importar los CryptoKeyVersions que se importaron antes.
El material de clave que se vuelve a importar debe coincidir exactamente con el material de clave original si la versión se importó correctamente antes.
Las CryptoKeyVersions destruidas antes del lanzamiento de esta función no se pueden volver a importar. El campo reimport_eligible de CryptoKeyVersion es true si la versión es apta para volver a importarla y false si no lo es.

Las claves de software y de Cloud HSM se pueden volver a importar, pero las claves externas no.

Vuelve a importar una clave destruida

Crea un objeto ImportJob para volver a importarlo siguiendo los pasos que se indican en Crea el trabajo de importación. Puedes usar una ImportJob existente o una ImportJob nueva, siempre que el nivel de protección coincida con el nivel de protección original.

Console

En la consola de Google Cloud , ve a la página Administración de claves.

Ir a Key Management
Haz clic en el nombre del llavero de claves que contiene la clave cuya versión volverás a importar.
Haz clic en la clave cuya versión quieres volver a importar.
Haz clic en los tres puntos junto a la versión de la clave que deseas volver a importar.
Selecciona Volver a importar la versión de clave.
Selecciona tu trabajo de importación en el menú desplegable Seleccionar trabajo de importación.
En el selector Subir la clave unida (Upload the wrapped key), selecciona la clave que ya uniste. Esta clave debe coincidir con el material de la clave original.
Haz clic en Reimportar.

gcloud

Para usar Cloud KMS en la línea de comandos, primero instala o actualiza a la versión más reciente de Google Cloud CLI.

Vuelve a importar la versión de clave con el material de clave 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

En estos ejemplos, se usa curl como un cliente HTTP para demostrar el uso de la API. Para obtener más información sobre el control de acceso, consulta Accede a la API de Cloud KMS.

En el cuerpo de la solicitud del método cryptoKeyVersions.import, configura el campo cryptoKeyVersion en el nombre de la versión de la clave que se importa. Debe ser un elemento secundario de la clave de criptografía.
En el cuerpo de la solicitud, configura el campo algorithm en el algoritmo de la clave que se importa. Este valor debe coincidir con el algoritmo de la versión de clave original. El campo algorithm es del tipo CryptoKeyVersionAlgorithm.
En el cuerpo de la solicitud, configura el campo wrappedKeyMaterial con el material de clave que ya uniste.
Llama al método cryptoKeyVersions.import. La respuesta cryptoKeyVersions.import es del tipo CryptoKeyVersion. Cuando una clave se importa con éxito, su estado es ENABLED, y puedes usarla a través de Cloud KMS.

¿Qué sigue?

Verifica una clave importada. Después de confirmar que el material de clave importado es idéntico a la clave original, puedes usar la clave para firmar o proteger datos.
Solucionar problemas de importación de una clave con errores

Configura la unión automática de claves

Verifica una versión de clave importada

Importa una versión de clave a Cloud KMS Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Antes de comenzar

Prepara el proyecto

Prepara el sistema local

Prepara la clave

Crea la clave de segmentación y el llavero de claves

Console

gcloud

Go

Java

Node.js

Python

API

Crea el trabajo de importación

Console

gcloud

Go

Java

Node.js

Python

API

Verifica el estado del trabajo de importación

Console

gcloud

Go

Java

Node.js

Python

API

Cómo evitar la modificación de trabajos de importación

Importa la clave

Importa y une una clave de forma automática

Importa una clave unida de forma manual

Console

gcloud

Go

Java

Node.js

Python

API

Verifica el estado de la versión de clave importada

Console

gcloud

Go

Java

Node.js

Python

API

Claves simétricas: Configura la versión principal

Vuelve a importar una clave destruida previamente

Restricciones

Vuelve a importar una clave destruida

Console

gcloud

API

¿Qué sigue?

Importa una versión de clave a Cloud KMS