Importar una versión de clave en Cloud KMS

En este tema se explica cómo importar una clave criptográfica en Cloud HSM o Cloud Key Management Service como una nueva versión de la clave.

Para obtener más información sobre la importación de claves, incluidas las limitaciones y restricciones, consulta el artículo sobre la importación de claves.

Puedes completar los pasos de este tema en un plazo de entre 5 y 10 minutos, sin incluir los pasos de la sección Antes de empezar. Encapsular la clave manualmente añade complejidad a la tarea.

Antes de empezar

Te recomendamos que crees un proyecto para probar esta función, de modo que te resulte más fácil eliminarlo después de las pruebas y que tengas los permisos de gestión de identidades y accesos (IAM) adecuados para importar una clave.

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

Preparar el proyecto

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

  2. 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 (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the required API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

  5. Install the Google Cloud CLI.

  6. Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

  7. Para inicializar gcloud CLI, ejecuta el siguiente comando: 

    gcloud init

  8. 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 (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  9. Verify that billing is enabled for your Google Cloud project.

  10. Enable the required API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

  11. Install the Google Cloud CLI.

  12. Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

  13. Para inicializar gcloud CLI, ejecuta el siguiente comando: 

    gcloud init

  14. El usuario que realice la importación debe tener los siguientes permisos de gestión de identidades y accesos para crear conjuntos de claves, 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 gestión de identidades y accesos disponibles para Cloud KMS, consulta Permisos y roles.

    15. Preparar el sistema local

    Prepara el sistema local eligiendo una de las siguientes opciones. Se recomienda la envoltura automática de claves para la mayoría de los usuarios.

    Preparar la clave

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

    Por otro lado, también debes verificar cómo se codifica la clave y hacer los ajustes necesarios.

    No se puede cambiar lo siguiente en una versión de clave después de crearla o importarla:

    • El nivel de protección indica si la clave se conserva en el software, en un HSM o en un sistema de gestión de claves externo. El material de claves no se puede mover de uno de estos entornos de almacenamiento a otro. Todas las versiones de una llave tienen el mismo nivel de protección.

    • El propósito indica si las versiones de la clave se usan para el cifrado simétrico, el cifrado asimétrico o la firma asimétrica. La finalidad de la clave limita los 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 ninguna clave para importar, pero quieres validar el procedimiento para importar 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 hacer pruebas. Es posible que una clave creada de esta forma no sea adecuada para usarla en producción.

    Si necesitas envolver la clave manualmente, hazlo antes de continuar con los procedimientos de este tema.

    Crear la clave y el conjunto de claves de destino

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

    Cuando importas una clave en Cloud KMS o Cloud HSM, la clave importada se convierte en una nueva versión de una clave de Cloud KMS o Cloud HSM. En el resto de este tema, esta clave se denomina clave de destino. La clave de destino debe existir para poder importar material de clave en ella.

    Importar una versión de una clave no afecta a las versiones que ya tenga esa clave. Sin embargo, se recomienda crear una clave vacía al probar la importación de claves. Una clave vacía no tiene ninguna versión, no está activa y no se puede usar.

    También puedes especificar que la clave recién creada solo pueda contener versiones importadas, lo que evita que se generen nuevas versiones por error en Cloud KMS.

    Una clave existe en un conjunto de claves. En este tema, este conjunto de claves se denomina conjunto de claves de destino. La ubicación del conjunto de claves de destino determina la ubicación en la que estará disponible el material de clave después de la importación. Las claves de Cloud HSM no se pueden crear ni importar en algunas ubicaciones. Una vez creada una clave, no se puede mover a otro llavero ni a otra ubicación.

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

    Consola

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

      Ir a Administración de claves

    2. Haz clic en Crear conjunto de claves.

    3. En el campo Nombre del conjunto de claves, introduce el nombre del conjunto de claves.

    4. En Tipo de ubicación, seleccione un tipo de ubicación y una ubicación.

    5. Haz clic en Crear. Se abrirá la página Crear clave.

    6. En el campo Nombre de la clave, introduce el nombre de la clave.

    7. En Nivel de protección, selecciona Software o HSM y, a continuación, haz clic en Continuar.

    8. En Material de clave, selecciona Clave importada y, a continuación, haz clic en Continuar. De esta forma, se evita que se cree una versión inicial de la clave.

    9. Define el Propósito y el Algoritmo de la clave y, a continuación, haz clic en Continuar.

    10. Opcional: Si quieres que esta clave contenga solo versiones de claves importadas, selecciona Restringir versiones de claves solo a importaciones. De esta forma, no crearás versiones de claves nuevas por error en Cloud KMS.

    11. 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 Periodo de rotación de claves.

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

    12. 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 la CLI de Google Cloud.

    1. Crea el conjunto de claves de destino. Si quieres importar una clave de Cloud HSM, selecciona una ubicación compatible con Cloud HSM.

      gcloud kms keyrings create KEY_RING \
  --location LOCATION

      Más información sobre cómo crear conjuntos de claves

    2. Crea la clave de destino.

      • Especifica el propósito de la clave.
      • Para evitar que se cree una versión inicial, usa la marca --skip-initial-version-creation.
      • Opcional: Para evitar que se creen nuevas versiones en Cloud KMS, usa la marca --import-only.
      • Opcional: No especifiques una política de rotación. Si habilitas la rotación automática, se generarán nuevas versiones de la clave en Cloud KMS y la versión de la clave importada dejará de ser la versión predeterminada después de una rotación. No puedes especificar una política de rotación si has especificado la marca --import-only.
      gcloud kms keys create KEY_NAME \
  --location LOCATION \
  --keyring KEY_RING \
  --purpose PURPOSE \
  --skip-initial-version-creation \
  --import-only

      Puedes consultar más información sobre cómo crear claves de Cloud KMS o claves de Cloud HSM.

    Go

    Para ejecutar este código, primero debes configurar un entorno de desarrollo de Go e instalar el SDK de Go de 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 debes configurar un entorno de desarrollo de Java e instalar el SDK de Java de 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 debes configurar un entorno de desarrollo de Node.js e instalar el SDK de Node.js de 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 debes configurar un entorno de desarrollo de Python e instalar el SDK de Python de 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 cliente HTTP para mostrar cómo se usa la API. Para obtener más información sobre el control de acceso, consulta el artículo sobre cómo acceder a la API Cloud KMS.

    1. Para crear un conjunto de claves:

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

      Para obtener más información, consulta la documentación de la API KeyRing.create.

    2. Crea una clave vacía que solo se pueda importar:

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

      Para obtener más información, consulta la documentación de la API CryptoKey.create.

    El conjunto de claves y la clave ya existen, pero la clave no contiene material de clave, no tiene ninguna versión y no está activa. A continuación, crea una tarea de importación.

    Crear la tarea de importación

    Una tarea 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 esta tarea de importación residirán en software, en un HSM o en un sistema de gestión de claves externo. El nivel de protección no se puede cambiar una vez que se haya importado la clave.

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

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

    Consola

    1. Ve a la página Gestión de claves de la Google Cloud consola.

      Ve a la página Gestión de claves.

    2. Haz clic en el nombre del conjunto de claves de destino.

    3. Define el Nivel de protección como Software o HSM. Usa el mismo nivel de protección que hayas definido para la clave de destino.

    4. Haz clic en Crear tarea de importación.

    5. En el campo Name (Nombre), introduce el nombre del trabajo de importación.

    6. En el menú desplegable Método de importación, selecciona RSA de 3072 bits o RSA de 4096 bits.

    7. 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 la CLI de Google Cloud.

    Usa un comando como el siguiente para crear una tarea 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 y la misma ubicación que la clave de destino.
    • Define el nivel de protección como software o hsm.
    • Define el método de importación 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 o rsa-oaep-4096-sha256.

    Go

    Para ejecutar este código, primero debes configurar un entorno de desarrollo de Go e instalar el SDK de Go de 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 debes configurar un entorno de desarrollo de Java e instalar el SDK de Java de 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 debes configurar un entorno de desarrollo de Node.js e instalar el SDK de Node.js de 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 debes configurar un entorno de desarrollo de Python e instalar el SDK de Python de 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 cliente HTTP para mostrar cómo se usa la API. Para obtener más información sobre el control de acceso, consulta el artículo sobre cómo acceder a la API Cloud KMS.

    Para crear una tarea 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"}'

    Haz los cambios siguientes:

    Comprobar el estado de la tarea de importación

    El estado inicial de una tarea de importación es PENDING_GENERATION. Cuando el estado sea ACTIVE, podrás usarlo para importar claves.

    Las tareas de importación caducan al cabo de tres días. Si la tarea de importación ha caducado, debes crear una nueva.

    Puedes consultar el estado de un trabajo de importación mediante la CLI de Google Cloud, laGoogle Cloud consola o la API Cloud Key Management Service.

    Consola

    1. Ve a la página Gestión de claves de la Google Cloud consola.

      Ve a la página Gestión de claves.

    2. Haga clic en el nombre del conjunto de claves que contiene su tarea de importación.

    3. En la parte superior de la página, haga clic en la pestaña Trabajos de importación.

    4. El estado se mostrará en Estado junto al nombre del 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 la CLI de Google Cloud.

    Cuando una tarea de importación está activa, puede usarla para importar claves. Este proceso puede tardar unos minutos. Usa este comando para verificar que la tarea de importación esté activa. Usa la ubicación y el llavero en los que has creado la tarea de importación.

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

    El resultado debería ser similar al siguiente:

    state: ACTIVE

    Go

    Para ejecutar este código, primero debes configurar un entorno de desarrollo de Go e instalar el SDK de Go de 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 debes configurar un entorno de desarrollo de Java e instalar el SDK de Java de 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 debes configurar un entorno de desarrollo de Node.js e instalar el SDK de Node.js de 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 debes configurar un entorno de desarrollo de Python e instalar el SDK de Python de 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 cliente HTTP para mostrar cómo se usa la API. Para obtener más información sobre el control de acceso, consulta el artículo sobre cómo acceder a la API Cloud KMS.

    Para comprobar el estado de una tarea 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 la tarea de importación esté activa, podrá solicitar la importación de una clave.

    Impedir la modificación de tareas de importación

    La tarea de importación determina muchas características de la clave importada, como el algoritmo de la clave y si se trata de una clave de HSM o de una clave de software. Puedes configurar permisos de gestión de identidades y accesos para impedir que los usuarios creen tareas de importación, pero permitirles que usen tareas de importación para importar claves.

    1. Concede el permiso importjobs.create solo a los administradores principales.
    2. Concede el permiso importjobs.useToImport para una tarea de importación específica al operador que vaya a usar esa tarea para importar claves.
    3. Cuando crees la tarea de importación, especifica el nivel de protección y el algoritmo de las versiones de clave que se importen con ella.

    Hasta que caduque la tarea de importación, los usuarios que tengan el permiso importjobs.useToImport y no tengan el permiso importjobs.create para una tarea de importación determinada podrán importar claves, pero no podrán modificar las características de la tarea de importación.

    Importar la clave

    Después de comprobar el estado de la tarea de importación, puedes enviar una solicitud de importación.

    Utiliza diferentes marcas para hacer la solicitud de importación, en función de si quieres que la CLI de Google Cloud envuelva tu clave automáticamente o si ya la has envuelto manualmente.

    Tanto si has envuelto la clave de forma manual como automática, debes definir el algoritmo como un algoritmo compatible que coincida con la longitud de la clave que se va a importar y especificar el propósito de la clave.

    • Las claves con el 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 una clave no se puede cambiar una vez que se ha creado, pero se pueden crear versiones posteriores de la clave con una longitud diferente a la de la versión inicial.

    .

    Encapsular e importar automáticamente una clave

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

    De forma opcional, puedes definir la marca --public-key-file en la ubicación en la que ya se haya descargado la clave pública. Al importar un gran número de claves, se evita que la clave pública se descargue durante cada importación. Por ejemplo, puedes escribir una secuencia de comandos que descargue la clave pública una vez y, a continuación, proporcione su ubicación al importar 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 encapsula con la clave de encapsulamiento asociada a la tarea de importación, se transmite a Google Cloudy se importa como una nueva versión de la clave de destino.

    Importar una clave encapsulada manualmente

    Sigue las instrucciones de esta sección para importar una clave que hayas envuelto manualmente. Define --wrapped-key-file como la ubicación de la clave que has envuelto manualmente. No definas --target-key-file.

    De forma opcional, puedes definir la marca --public-key-file en la ubicación en la que ya se haya descargado la clave pública. Al importar un gran número de claves, se evita que la clave pública se descargue durante cada importación. Por ejemplo, puedes escribir una secuencia de comandos que descargue la clave pública una vez y, a continuación, proporcione su ubicación al importar cada clave.

    Consola

    1. Abre la página Gestión de claves en la consola deGoogle Cloud .

    2. Haga clic en el nombre del conjunto de claves que contiene su tarea de importación. Se muestra la clave de destino junto con cualquier otra clave del llavero.

    3. Haga clic en el nombre de la clave de destino y, a continuación, en Importar versión de clave.

    4. Selecciona la tarea de importación en el menú desplegable Seleccionar tarea de importación.

    5. En el selector Cargar la clave incorporada, selecciona la clave que ya hayas incorporado.

    6. Si vas a importar una clave asimétrica, selecciona el algoritmo en el menú desplegable Algoritmo. La página Importar versión de clave debería tener un aspecto similar al siguiente:

      Importar versión de clave

    7. 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 la CLI de Google Cloud.

    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 debes configurar un entorno de desarrollo de Go e instalar el SDK de Go de 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 debes configurar un entorno de desarrollo de Java e instalar el SDK de Java de 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 debes configurar un entorno de desarrollo de Node.js e instalar el SDK de Node.js de 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 debes configurar un entorno de desarrollo de Python e instalar el SDK de Python de 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 cliente HTTP para mostrar cómo se usa la API. Para obtener más información sobre el control de acceso, consulta el artículo sobre cómo acceder a la API 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"}'

    Haz los cambios siguientes:

    • IMPORT_JOB_ID: el nombre completo del recurso del trabajo de importación correspondiente.

    • ALGORITHM: el algorithm de la clave que se importa, que es de tipo CryptoKeyVersionAlgorithm.

    • WRAPPED_KEY: la clave envuelta manualmente en formato base64.

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

    Comprobar el estado de la versión de la 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 ha importado correctamente. Si la importación falla, el estado es IMPORT_FAILED.

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

    Consola

    1. Abre la página Gestión de claves en la consola deGoogle Cloud .

    2. Haga clic en el nombre del conjunto de claves que contiene su tarea de importación.

    3. En la parte superior de la página, haga clic en la pestaña Trabajos de importación.

    4. El estado se mostrará en Estado junto al nombre del 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 la CLI de Google Cloud.

    Usa el comando versions list para comprobar el estado. Usa la misma ubicación, el mismo conjunto de claves de destino y la misma clave de destino que has creado anteriormente en este tema.

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

    Go

    Para ejecutar este código, primero debes configurar un entorno de desarrollo de Go e instalar el SDK de Go de 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 debes configurar un entorno de desarrollo de Java e instalar el SDK de Java de 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 debes configurar un entorno de desarrollo de Node.js e instalar el SDK de Node.js de 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 debes configurar un entorno de desarrollo de Python e instalar el SDK de Python de 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 cliente HTTP para mostrar cómo se usa la API. Para obtener más información sobre el control de acceso, consulta el artículo sobre cómo acceder a la API Cloud KMS.

    Llama al método ImportJob.get y comprueba el campo state. Si state es PENDING_GENERATION, la tarea de importación aún se está creando. Vuelve a comprobar el estado periódicamente hasta que sea ACTIVE.

    Una vez importada la versión inicial de la clave, el estado de la clave cambia a Activa. En el caso de las claves simétricas, debes definir la versión de la clave importada como versión principal para poder usarla.

    Claves simétricas: definir la versión principal

    Este paso es obligatorio al importar claves simétricas y no se aplica a las claves asimétricas. Las claves asimétricas no tienen una versión principal. Debes usar Google Cloud CLI para definir la versión principal.

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

    Volver a importar una clave destruida anteriormente

    Cloud Key Management Service admite la reimportación de claves, lo que te permite restaurar 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 ha importado material de clave original debido a un error de importación inicial, se puede proporcionar cualquier material de clave.

    Restricciones

    • Solo se pueden volver a importar los CryptoKeyVersions que se hayan importado previamente.
    • El material de clave que se vuelve a importar debe coincidir exactamente con el material de clave original si la versión se ha importado correctamente anteriormente.
    • CryptoKeyVersions destruidos 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 se puede volver a importar y false si no.

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

    Volver a importar una clave destruida

    Crea un ImportJob para volver a importar siguiendo los pasos que se indican en Crear la tarea de importación. Puede usar un ImportJob que ya tenga o crear uno nuevo, siempre que el nivel de protección coincida con el nivel de protección original.ImportJob

    Consola

    1. Ve a la página Gestión de claves de la Google Cloud consola.

      Ve a la página Gestión de claves.

    2. Haga clic en el nombre del conjunto de claves que contiene la clave cuya versión va a volver a importar.

    3. Haz clic en la clave cuya versión quieras volver a importar.

    4. Haz clic en los tres puntos situados junto a la versión de la clave que quieras volver a importar.

    5. Selecciona Volver a importar versión de clave.

    6. Selecciona la tarea de importación en el menú desplegable Seleccionar tarea de importación.

    7. En el selector Cargar la clave incorporada, selecciona la clave que ya hayas incorporado. Esta clave debe coincidir con el material de clave original.

    8. Haz clic en Re-Import (Volver a importar).

    gcloud

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

    1. Vuelve a importar la versión de la clave con el material de la 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 cliente HTTP para mostrar cómo se usa la API. Para obtener más información sobre el control de acceso, consulta el artículo sobre cómo acceder a la API Cloud KMS.

    1. En el cuerpo de la solicitud del método cryptoKeyVersions.import, asigna al campo cryptoKeyVersion el nombre de la versión de la clave que se va a importar. Debe ser un elemento secundario de la clave criptográfica.

    2. En el cuerpo de la solicitud, asigna al campo algorithm el algoritmo de la clave que se va a importar. Este valor debe coincidir con el algoritmo de la versión original de la clave. El campo algorithm es del tipo CryptoKeyVersionAlgorithm.

    3. En el cuerpo de la solicitud, asigna al campo wrappedKeyMaterial el material de clave que ya has envuelto.

    4. Llama al método cryptoKeyVersions.import. La respuesta cryptoKeyVersions.import es del tipo CryptoKeyVersion. Cuando se importa una clave correctamente, su estado es ENABLED y puedes usarla en Cloud KMS.

    Siguientes pasos

Anterior
Configura la unión de claves automática
Siguiente
Verifica una versión de clave importada