Schlüsselversion in Cloud KMS importieren

In diesem Thema erfahren Sie, wie Sie einen kryptografischen Schlüssel als neue Schlüsselversion in Cloud HSM oder Cloud Key Management Service importieren.

Weitere Informationen zum Importieren von Schlüsseln, einschließlich Beschränkungen und Einschränkungen, finden Sie unter Schlüsselimport.

Die in diesem Thema beschriebenen Schritte lassen sich in 5 bis 10 Minuten ausführen. Dabei sind die Schritte unter Vorbereitung nicht berücksichtigt. Wenn Sie den Schlüssel manuell verpacken, wird die Aufgabe komplexer.

Hinweise

Wir empfehlen, ein neues Projekt zu erstellen, um dieses Feature zu testen, die Bereinigung nach dem Testen zu vereinfachen und dafür zu sorgen, dass Sie die erforderlichen IAM-Berechtigungen (Identity and Access Management) zum Importieren eines Schlüssels haben.

Bevor Sie einen Schlüssel importieren können, müssen Sie das Projekt, das lokale System und den Schlüssel selbst vorbereiten.

Das Projekt vorbereiten

  1. Melden Sie sich bei Ihrem Google Cloud-Konto an. Wenn Sie mit Google Cloud noch nicht vertraut sind, erstellen Sie ein Konto, um die Leistungsfähigkeit unserer Produkte in der Praxis sehen und bewerten zu können. Neukunden erhalten außerdem ein Guthaben von 300 $, um Arbeitslasten auszuführen, zu testen und bereitzustellen.

  2. Wählen Sie in der Google Cloud Console auf der Seite der Projektauswahl ein Google Cloud-Projekt aus oder erstellen Sie eines.

    Zur Projektauswahl

  3. Die Abrechnung für das Google Cloud-Projekt muss aktiviert sein.

  4. Aktivieren Sie die erforderliche API.

    Aktivieren Sie die API

  5. Installieren Sie die Google Cloud CLI.

  6. Führen Sie folgenden Befehl aus, um die gcloud CLI zu initialisieren: 

    gcloud init
    7.

  7. Wählen Sie in der Google Cloud Console auf der Seite der Projektauswahl ein Google Cloud-Projekt aus oder erstellen Sie eines.

    Zur Projektauswahl

  8. Die Abrechnung für das Google Cloud-Projekt muss aktiviert sein.

  9. Aktivieren Sie die erforderliche API.

    Aktivieren Sie die API

  10. Installieren Sie die Google Cloud CLI.

  11. Führen Sie folgenden Befehl aus, um die gcloud CLI zu initialisieren: 

    gcloud init
    12.

  12. Der Nutzer, der den Import durchführt, benötigt die folgenden IAM-Berechtigungen, um Schlüsselbunde, Schlüssel und Importjobs zu erstellen. Wenn der Nutzer nicht der Projektinhaber ist, können Sie ihm beide der folgenden vordefinierten Rollen zuweisen:

    • roles/editor
    • roles/cloudkms.importer

    Weitere Informationen zu verfügbaren IAM-Rollen und -Berechtigungen für Cloud KMS finden Sie unter Berechtigungen und Rollen.

In lokalem Datenspeicher suchen

Bereiten Sie das lokale System vor, indem Sie eine der folgenden Optionen auswählen. Für die meisten Nutzer wird das automatische Key-Wrapping empfohlen.

  • Wenn Sie zulassen möchten, dass die Google Cloud CLI Ihre Schlüssel automatisch verpackt, bevor sie an Google Cloud übertragen werden, müssen Sie die Pyca Cryptography-Bibliothek auf Ihrem lokalen System installieren. Die Pyca-Bibliothek wird von dem Importjob verwendet, der den Schlüssel lokal verpackt und schützt, bevor er an Google Cloud gesendet wird.
  • Wenn Sie Ihre Schlüssel manuell verpacken möchten, müssen Sie OpenSSL für das manuelle Schlüssel-Wrapping konfigurieren.

Den Schlüssel vorbereiten

Prüfen Sie, ob Algorithmus und Länge Ihres Schlüssels unterstützt werden. Die zulässigen Algorithmen für einen Schlüssel hängen davon ab, ob der Schlüssel für die synchrone Verschlüsselung, die asymmetrische Verschlüsselung oder die asymmetrische Signatur verwendet wird und ob der Schlüssel in Software oder in einem HSM gespeichert ist. Sie geben den Algorithmus des Schlüssels als Teil der Importanfrage an.

Unabhängig davon müssen Sie auch prüfen, wie der Schlüssel codiert ist, und gegebenenfalls Anpassungen vornehmen.

Folgendes kann für eine Schlüsselversion nicht mehr geändert werden, nachdem sie erstellt oder importiert wurde:

  • Das Schutzniveau gibt an, ob der Schlüssel in der Software, in einem HSM oder in einem externen Schlüsselverwaltungssystem erhalten bleibt. Schlüsselmaterial kann nicht von einer dieser Speicherumgebungen in eine andere verschoben werden. Alle Versionen eines Schlüssels haben das gleiche Schutzniveau.

  • Der purpose gibt an, ob Versionen des Schlüssels für die symmetrische Verschlüsselung, für asymmetrische Verschlüsselung oder für asymmetrische Signaturen verwendet werden. Der Zweck des Schlüssels schränkt die möglichen Algorithmen ein, die zum Erstellen von Versionen dieses Schlüssels verwendet werden können. Alle Versionen eines Schlüssels haben denselben Zweck.

Wenn Sie keinen Schlüssel zum Importieren haben, aber das Verfahren zum Importieren von Schlüsseln prüfen möchten, können Sie mit dem folgenden Befehl einen symmetrischen Schlüssel auf dem lokalen System erstellen:

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

Verwenden Sie diesen Schlüssel nur zu Testzwecken. Ein in dieser Weise erstellter Schlüssel ist möglicherweise nicht für die Produktion geeignet.

Wenn Sie den Schlüssel manuell verpacken, dann tun Sie dies, bevor Sie mit den Verfahren in diesem Thema fortfahren.

Den Zielschlüssel und Schlüsselbund erstellen

Ein Cloud KMS-Schlüssel ist ein Containerobjekt, das null oder mehr Schlüsselversionen enthält. Jede Schlüsselversion hat einen kryptografischen Schlüssel.

Wenn Sie einen Schlüssel in Cloud KMS oder Cloud HSM importieren, wird der importierte Schlüssel zu einer neuen Schlüsselversion in einem vorhandenen Cloud KMS- oder Cloud HSM-Schlüssel. Im Folgenden wird dieser Schlüssel als Zielschlüssel bezeichnet. Der Zielschlüssel muss vorhanden sein, bevor Sie Schlüsselmaterial darin importieren können.

Das Importieren einer Schlüsselversion hat keine Auswirkungen auf die vorhandenen Versionen dieses Schlüssels. Es wird jedoch empfohlen, beim Testen des Schlüsselimports einen leeren Schlüssel zu erstellen. Ein leerer Schlüssel hat keine Version, ist nicht aktiv und kann nicht angewendet werden.

Optional können Sie angeben, dass Ihr neu erstellter Schlüssel nur importierte Versionen enthalten darf. Dadurch wird verhindert, dass in Cloud KMS versehentlich neue Versionen erstellt werden.

Ein Schlüssel befindet sich immer in einem Schlüsselbund. In diesem Thema wird dieser Schlüsselbund als Zielschlüsselbund bezeichnet. Der Speicherort des Zielschlüssels bestimmt, wo das Schlüsselmaterial nach dem Import verfügbar ist. Cloud HSM-Schlüssel können an einigen Standorten nicht erstellt oder importiert werden. Nachdem ein Schlüssel erstellt wurde, kann er nicht mehr zu einem anderen Schlüsselbund oder an einen anderen Speicherort verschoben werden.

Führen Sie die folgenden Schritte aus, um mit der Google Cloud CLI oder der Google Cloud Console einen leeren Schlüssel auf einem neuen Schlüsselbund zu erstellen.

Console

  1. Rufen Sie in der Google Cloud Console die Seite Schlüsselverwaltung auf.

    Key Management aufrufen

  2. Klicken Sie auf KeyRing erstellen.

  3. Geben Sie im Feld Schlüsselbundname einen Namen für den Schlüsselbund ein.

  4. Wählen Sie unter Standorttyp einen Standorttyp und einen Standort aus.

  5. Klicken Sie auf Erstellen. Die Seite Schlüssel erstellen wird geöffnet.

  6. Geben Sie im Feld Schlüsselname einen Namen für den Schlüssel ein.

  7. Wählen Sie als Schutzniveau entweder Software oder HSM aus und klicken Sie dann auf Weiter.

  8. Wählen Sie unter Schlüsselmaterial die Option Importierter Schlüssel aus und klicken Sie dann auf Weiter. Dadurch wird verhindert, dass eine anfängliche Schlüsselversion erstellt wird.

  9. Legen Sie den Zweck und den Algorithmus für den Schlüssel fest und klicken Sie dann auf Weiter.

  10. Optional: Wenn dieser Schlüssel nur importierte Schlüsselversionen enthalten soll, wählen Sie Schlüsselversionen nur auf Import einschränken aus. Dadurch wird verhindert, dass Sie versehentlich neue Schlüsselversionen in Cloud KMS erstellen.

  11. Optional: Für importierte Schlüssel ist die automatische Rotation standardmäßig deaktiviert. Wählen Sie einen Wert aus dem Feld Schlüsselrotationszeitraum aus, um die automatische Rotation zu aktivieren.

    Wenn Sie die automatische Rotation aktivieren, werden in Cloud KMS neue Schlüsselversionen generiert und die importierte Schlüsselversion nach einer Rotation nicht mehr die Standardversion.

  12. Klicken Sie auf Erstellen.

gcloud

Wenn Sie Cloud KMS in der Befehlszeile verwenden möchten, müssen Sie zuerst die neueste Version der Google Cloud CLI installieren oder ein Upgrade auf die neueste Version durchführen.

  1. Erstellen Sie den Zielschlüsselbund. Wenn Sie in einen Cloud HSM-Schlüssel importieren möchten, wählen Sie einen Standort mit Unterstützung für Cloud HSM aus.

    gcloud kms keyrings create KEY_RING \
  --location LOCATION

    Weitere Informationen zur Erstellung von Schlüsselbunden

  2. Erstellen Sie den Zielschlüssel.

    • Geben Sie den Zweck des Schlüssels an.
    • Mit dem Flag --skip-initial-version-creation verhindern Sie, dass eine anfängliche Version erstellt wird.
    • Optional: Mit dem Flag --import-only verhindern Sie das Erstellen neuer Versionen in Cloud KMS.
    • Optional: Geben Sie keine Rotationsrichtlinie an. Wenn Sie die automatische Rotation aktivieren, werden in Cloud KMS neue Schlüsselversionen generiert und die importierte Schlüsselversion nach einer Rotation nicht mehr die Standardversion. Sie können keine Rotationsrichtlinie angeben, wenn Sie das --import-only-Flag angegeben haben.
    gcloud kms keys create KEY_NAME \
  --location LOCATION \
  --keyring KEY_RING \
  --purpose PURPOSE \
  --skip-initial-version-creation \
  --import-only

    Hier erhalten Sie weitere Informationen zum Erstellen von Cloud KMS-Schlüsseln oder Cloud HSM-Schlüsseln

Go

Um diesen Code auszuführen, müssen Sie zuerst eine Go-Entwicklungsumgebung einrichten und das Cloud KMS Go SDK installieren.

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

Um diesen Code auszuführen, müssen Sie zuerst eine Java-Entwicklungsumgebung einrichten und das Cloud KMS Java SDK installieren.

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

Um diesen Code auszuführen, richten Sie zuerst eine Node.js-Entwicklungsumgebung ein und installieren Sie das Cloud KMS Node.js SDK.

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

Um diesen Code auszuführen, müssen Sie zuerst eine Python-Entwicklungsumgebung einrichten und das Cloud KMS Python SDK installieren.

from google.cloud import kms

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

    Sets up an empty CryptoKey within a KeyRing for import.

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

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

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

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

    # Call the API.
    created_key = client.create_crypto_key(
        request={
            "parent": key_ring_name,
            "crypto_key_id": crypto_key_id,
            "crypto_key": key,
        }
    )
    print(f"Created hsm key: {created_key.name}")

API

In diesen Beispielen wird curl als HTTP-Client verwendet, um die Verwendung der API zu demonstrieren. Weitere Informationen zur Zugriffssteuerung finden Sie unter Auf die Cloud KMS API zugreifen.

  1. Erstellen Sie einen neuen Schlüsselbund:

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

    Weitere Informationen finden Sie in der KeyRing.create API-Dokumentation.

  2. Erstellen Sie einen leeren Importschlüssel:

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

    Weitere Informationen finden Sie in der CryptoKey.create API-Dokumentation.

Der Schlüsselbund und der Schlüssel sind jetzt vorhanden, aber der Schlüssel enthält kein Schlüsselmaterial, keine Version und ist nicht aktiv. Als Nächstes erstellen Sie einen Importjob.

Erstellen Sie den Importjob

Ein Importjob definiert die Merkmale der importierten Schlüssel, einschließlich der Attribute, die nach dem Import des Schlüssels nicht mehr geändert werden können.

Das Schutzniveau definiert, ob sich die von diesem Importjob importierten Schlüssel in Software, in einem HSM oder in einem externen Schlüsselverwaltungssystem befinden. Das Schutzniveau kann nicht mehr geändert werden, nachdem der Schlüssel schließlich importiert wurde.

Die Importmethode definiert den Algorithmus, der zum Erstellen des Verpackungsschlüssels verwendet wird, der importierte Schlüssel bei der Übertragung von Ihrem lokalen System zum Google Cloud-Zielprojekt schützt. Sie können einen RSA-Schlüssel mit 3.072 Bit oder 4.096 Bit auswählen. Wenn es keine speziellen Anforderungen gibt, wird der 3.072-Bit-Verpackungsschlüssel empfohlen.

Sie können einen Importjob mit der gcloud CLI, der Google Cloud Console oder der Cloud Key Management Service API erstellen.

Console

  1. Rufen Sie in der Google Cloud Console die Seite Schlüsselverwaltung auf.

    Zur Seite „Schlüsselverwaltung“

  2. Klicken Sie auf den Namen des Zielschlüsselbunds.

  3. Setzen Sie das Schutzniveau entweder auf Software oder auf HSM. Verwenden Sie dasselbe Schutzniveau wie für den Zielschlüssel.

  4. Klicken Sie auf Importjob erstellen.

  5. Geben Sie im Feld Name einen Namen für den Importjob ein.

  6. Wählen Sie im Drop-down-Menü Importmethode entweder 3.072-Bit-RSA oder 4.096-Bit-RSA aus.

  7. Klicken Sie auf Erstellen.

gcloud

Wenn Sie Cloud KMS in der Befehlszeile verwenden möchten, müssen Sie zuerst die neueste Version der Google Cloud CLI installieren oder ein Upgrade auf die neueste Version durchführen.

Einen Importjob erstellen Sie mit einem Befehl wie dem folgenden.

gcloud kms import-jobs create IMPORT_JOB \
  --location LOCATION \
  --keyring KEY_RING \
  --import-method IMPORT_METHOD \
  --protection-level PROTECTION_LEVEL
  • Verwenden Sie denselben Schlüsselbund und denselben Speicherort wie der Zielschlüssel.
  • Legen Sie das Schutzniveau auf software oder hsm fest.
  • Legen Sie die Importmethode auf 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 oder rsa-oaep-4096-sha256 fest.

Go

Um diesen Code auszuführen, müssen Sie zuerst eine Go-Entwicklungsumgebung einrichten und das Cloud KMS Go SDK installieren.

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

Um diesen Code auszuführen, müssen Sie zuerst eine Java-Entwicklungsumgebung einrichten und das Cloud KMS Java SDK installieren.

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

Um diesen Code auszuführen, richten Sie zuerst eine Node.js-Entwicklungsumgebung ein und installieren Sie das Cloud KMS Node.js SDK.

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

Um diesen Code auszuführen, müssen Sie zuerst eine Python-Entwicklungsumgebung einrichten und das Cloud KMS Python SDK installieren.

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

In diesen Beispielen wird curl als HTTP-Client verwendet, um die Verwendung der API zu demonstrieren. Weitere Informationen zur Zugriffssteuerung finden Sie unter Auf die Cloud KMS API zugreifen.

Verwenden Sie zum Erstellen eines Importjobs die Methode 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"}'

Ersetzen Sie Folgendes:

Status des Importjobs überprüfen

Der Ausgangsstatus für einen Importjob ist PENDING_GENERATION. Wenn der Status ACTIVE lautet, können Sie damit Schlüssel importieren.

Ein Importjob läuft nach drei Tagen ab. Wenn der Importjob abgelaufen ist, müssen Sie einen neuen erstellen.

Sie können den Status eines Importjobs über die Google Cloud CLI, die Google Cloud Console oder die Cloud Key Management Service API prüfen.

Console

  1. Rufen Sie in der Google Cloud Console die Seite Schlüsselverwaltung auf.

    Zur Seite „Schlüsselverwaltung“

  2. Klicken Sie auf den Namen des Schlüsselbunds, der den Importjob enthält.

  3. Klicken Sie oben auf der Seite auf den Tab Importjobs.

  4. Der Status wird unter Status neben dem Namen des Importjobs angezeigt.

gcloud

Wenn Sie Cloud KMS in der Befehlszeile verwenden möchten, müssen Sie zuerst die neueste Version der Google Cloud CLI installieren oder ein Upgrade auf die neueste Version durchführen.

Wenn ein Importjob aktiv ist, können Sie damit Schlüssel importieren. Dies kann einige Minuten dauern. Überprüfen Sie mit diesem Befehl, ob der Importjob aktiv ist. Verwenden Sie den Speicherort und den Schlüsselbund, an dem Sie den Importjob erstellt haben.

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

Die Ausgabe sieht in etwa so aus:

state: ACTIVE

Go

Um diesen Code auszuführen, müssen Sie zuerst eine Go-Entwicklungsumgebung einrichten und das Cloud KMS Go SDK installieren.

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

Um diesen Code auszuführen, müssen Sie zuerst eine Java-Entwicklungsumgebung einrichten und das Cloud KMS Java SDK installieren.

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

Um diesen Code auszuführen, richten Sie zuerst eine Node.js-Entwicklungsumgebung ein und installieren Sie das Cloud KMS Node.js SDK.

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

Um diesen Code auszuführen, müssen Sie zuerst eine Python-Entwicklungsumgebung einrichten und das Cloud KMS Python SDK installieren.

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

In diesen Beispielen wird curl als HTTP-Client verwendet, um die Verwendung der API zu demonstrieren. Weitere Informationen zur Zugriffssteuerung finden Sie unter Auf die Cloud KMS API zugreifen.

Verwenden Sie die Methode ImportJobs.get, um den Status eines Importjobs zu prüfen:

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

Sobald der Importjob aktiv ist, können Sie eine Anfrage zum Importieren eines Schlüssels stellen.

Änderungen an Importjobs verhindern

Der Importjob bestimmt viele Eigenschaften des importierten Schlüssels, einschließlich seines Algorithmus und ob ein importierter Schlüssel ein HSM- oder Softwareschlüssel ist. Sie können IAM-Berechtigungen konfigurieren, um zu verhindern, dass Nutzer Importjobs erstellen, und ihnen gleichzeitig erlauben, Importjobs zum Importieren von Schlüsseln zu verwenden.

  1. Erteilen Sie die Berechtigung importjobs.create nur Schlüsseladministratoren.
  2. Erteilen Sie dem Operator, der diesen Job zum Importieren von Schlüsseln verwendet, die Berechtigung importjobs.useToImport für einen bestimmten Importjob.
  3. Geben Sie beim Erstellen des Importjobs das Schutzniveau und den Algorithmus für die mit ihm importierten Schlüsselversionen an.

Bis zum Ablauf des Importjobs können Nutzer, die importjobs.useToImport und nicht die Berechtigung importjobs.create für einen bestimmten Importjob haben, Schlüssel importieren, jedoch nicht die Eigenschaften des Importjobs ändern.

Importieren Sie den Schlüssel

Nachdem Sie den Status des Importjobs überprüft haben, können Sie eine Importanfrage stellen.

Für die Importanfrage verwenden Sie unterschiedliche Flags, je nachdem, ob die Google Cloud CLI den Schlüssel automatisch verpacken soll oder den Schlüssel bereits manuell verpackt haben.

Unabhängig davon, ob Sie Ihren Schlüssel manuell oder automatisch verpackt haben, müssen Sie unter Algorithmus einen unterstützten Algorithmus festlegen, der der Länge des tatsächlich zu importierenden Schlüssels entspricht und den Zweck des Schlüssels angibt.

  • Schlüssel mit dem Zweck ENCRYPT_DECRYPT verwenden den Algorithmus google-symmetric-encryption und haben eine Länge von 32.

  • Schlüssel mit dem Zweck ASYMMETRIC_DECRYPT oder ASYMMETRIC_SIGN unterstützen eine Vielzahl von Algorithmen und Längen.

    Der Zweck eines Schlüssels kann nach dem Erstellen des Schlüssels nicht mehr geändert werden. Für nachfolgende Schlüsselversionen können Sie jedoch eine andere Länge als die ursprüngliche Schlüsselversion festlegen.

Schlüssel automatisch verpacken und importieren

Wenn Sie das automatische Wrapping verwenden möchten, müssen Sie die Google Cloud CLI verwenden. Verwenden Sie einen Befehl wie den folgenden. Legen Sie für --target-key-file den Speicherort des entpackten Schlüssels fest, der verpackt und importiert werden soll. Legen Sie nicht --wrapped-key-file fest.

Sie können das Flag --public-key-file optional auf den Speicherort festlegen, an dem der öffentliche Schlüssel bereits heruntergeladen wurde. Beim Importieren einer großen Anzahl von Schlüsseln wird dadurch verhindert, dass der öffentliche Schlüssel bei jedem Import heruntergeladen wird. Sie können beispielsweise ein Skript schreiben, das den öffentlichen Schlüssel einmal herunterlädt und dann beim Importieren jedes Schlüssels seinen Speicherort angibt.

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

Der Schlüssel wird von dem Verpackungsschlüssel, der dem Importjob zugeordnet ist, verpackt, an Google Cloud übertragen und als neue Schlüsselversion für den Zielschlüssel importiert.

Manuell verpackten Schlüssel importieren

Folgen Sie der Anleitung in diesem Abschnitt, um einen manuell verpackten Schlüssel zu importieren. Legen Sie für --wrapped-key-file den Speicherort des manuell verpackten Schlüssels fest. Legen Sie nicht --target-key-file fest.

Sie können das Flag --public-key-file optional auf den Speicherort festlegen, an dem der öffentliche Schlüssel bereits heruntergeladen wurde. Beim Importieren einer großen Anzahl von Schlüsseln wird dadurch verhindert, dass der öffentliche Schlüssel bei jedem Import heruntergeladen wird. Sie können beispielsweise ein Skript schreiben, das den öffentlichen Schlüssel einmal herunterlädt und dann beim Importieren jedes Schlüssels seinen Speicherort angibt.

Console

  1. Öffnen Sie in der Google Cloud Console die Seite Schlüsselverwaltung.

  2. Klicken Sie auf den Namen des Schlüsselbunds, der den Importjob enthält. Der Zielschlüssel wird zusammen mit allen anderen Schlüsseln auf dem Schlüsselbund angezeigt.

  3. Klicken Sie auf den Namen des Zielschlüssels und dann auf Schlüsselversion importieren.

  4. Wählen Sie den Importjob aus dem Drop-down-Menü Importjob auswählen aus.

  5. Wählen Sie aus der Auswahl Verpackten Schlüssel hochladen den Schlüssel aus, den Sie bereits verpackt haben.

  6. Wenn Sie einen asymmetrischen Schlüssel importieren, wählen Sie den Algorithmus aus dem Drop-down-Menü Algorithmus aus. Die Seite Schlüsselversion importieren sollte in etwa so aussehen:

    Schlüsselversion importieren

  7. Klicken Sie auf Import (Importieren).

gcloud

Wenn Sie Cloud KMS in der Befehlszeile verwenden möchten, müssen Sie zuerst die neueste Version der Google Cloud CLI installieren oder ein Upgrade auf die neueste Version durchführen.

Verwenden Sie einen Befehl wie den folgenden.

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

Weitere Informationen finden Sie in der Ausgabe des Befehls gcloud kms keys versions import --help.

Go

Um diesen Code auszuführen, müssen Sie zuerst eine Go-Entwicklungsumgebung einrichten und das Cloud KMS Go SDK installieren.

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

Um diesen Code auszuführen, müssen Sie zuerst eine Java-Entwicklungsumgebung einrichten und das Cloud KMS Java SDK installieren.

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

Um diesen Code auszuführen, richten Sie zuerst eine Node.js-Entwicklungsumgebung ein und installieren Sie das Cloud KMS Node.js SDK.

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

Um diesen Code auszuführen, müssen Sie zuerst eine Python-Entwicklungsumgebung einrichten und das Cloud KMS Python SDK installieren.

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

In diesen Beispielen wird curl als HTTP-Client verwendet, um die Verwendung der API zu demonstrieren. Weitere Informationen zur Zugriffssteuerung finden Sie unter Auf die Cloud KMS API zugreifen.

Verwenden Sie die Methode cryptoKeyVersions.import, um einen Schlüssel zu importieren.

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

Ersetzen Sie Folgendes:

  • IMPORT_JOB_ID: der vollständige Ressourcenname des entsprechenden Importjobs.

  • ALGORITHM: algorithm des zu importierenden Schlüssels vom Typ CryptoKeyVersionAlgorithm.

  • WRAPPED_KEY: der manuell verpackte Schlüssel im base64-Format.

Die Anfrage für den Schlüsselimport wird initiiert. Sie können den Status überwachen.

Status der importierten Schlüsselversion prüfen

Der Anfangsstatus für eine importierte Schlüsselversion ist PENDING_IMPORT. Wenn der Status ENABLED lautet, wurde die Schlüsselversion erfolgreich importiert. Wenn der Import fehlschlägt, ist der Status IMPORT_FAILED.

Sie können den Status einer Importanfrage mithilfe der Google Cloud CLI, der Google Cloud Console oder der Cloud Key Management Service API prüfen.

Console

  1. Öffnen Sie in der Google Cloud Console die Seite Schlüsselverwaltung.

  2. Klicken Sie auf den Namen des Schlüsselbunds, der den Importjob enthält.

  3. Klicken Sie oben auf der Seite auf den Tab Importjobs.

  4. Der Status wird unter Status neben dem Namen des Importjobs angezeigt.

gcloud

Wenn Sie Cloud KMS in der Befehlszeile verwenden möchten, müssen Sie zuerst die neueste Version der Google Cloud CLI installieren oder ein Upgrade auf die neueste Version durchführen.

Prüfen Sie den Status mithilfe des Befehls versions list. Verwenden Sie denselben Speicherort, denselben Schlüsselbund und denselben Schlüssel, den Sie zuvor in diesem Thema erstellt haben.

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

Go

Um diesen Code auszuführen, müssen Sie zuerst eine Go-Entwicklungsumgebung einrichten und das Cloud KMS Go SDK installieren.

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

Um diesen Code auszuführen, müssen Sie zuerst eine Java-Entwicklungsumgebung einrichten und das Cloud KMS Java SDK installieren.

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

Um diesen Code auszuführen, richten Sie zuerst eine Node.js-Entwicklungsumgebung ein und installieren Sie das Cloud KMS Node.js SDK.

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

Um diesen Code auszuführen, müssen Sie zuerst eine Python-Entwicklungsumgebung einrichten und das Cloud KMS Python SDK installieren.

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

In diesen Beispielen wird curl als HTTP-Client verwendet, um die Verwendung der API zu demonstrieren. Weitere Informationen zur Zugriffssteuerung finden Sie unter Auf die Cloud KMS API zugreifen.

Rufen Sie die Methode ImportJob.get auf und überprüfen Sie das Feld state. Wenn state PENDING_GENERATION lautet, wird der Importjob noch erstellt. Prüfen Sie den Status regelmäßig, bis er ACTIVE lautet.

Nachdem die ursprüngliche Schlüsselversion importiert wurde, ändert sich der Status des Schlüssels in Aktiv. Bei symmetrischen Schlüsseln müssen Sie die importierte Schlüsselversion als primäre Version festlegen, bevor Sie den Schlüssel verwenden können.

Symmetrische Schlüssel: Legen Sie die primäre Version fest

Dieser Schritt ist beim Importieren von Symmetrieschlüsseln erforderlich und für asymmetrische Schlüssel nicht relevant. Ein asymmetrischer Schlüssel hat keine primäre Version. Sie müssen die Google Cloud CLI verwenden, um die Hauptversion festzulegen.

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

Einen gelöschten Schlüssel noch einmal importieren

Cloud Key Management Service unterstützt den Reimport von Schlüsseln. Damit können Sie eine zuvor importierte Schlüsselversion im Status DESTROYED oder IMPORT_FAILED im Status ENABLED wiederherstellen, indem Sie das ursprüngliche Schlüsselmaterial bereitstellen. Wenn aufgrund eines Fehlers beim ersten Import noch nie ein ursprüngliches Schlüsselmaterial importiert wurde, kann ein beliebiges Schlüsselmaterial angegeben werden.

Einschränkungen

  • Nur zuvor importierte CryptoKeyVersions können noch einmal importiert werden.
  • Neu importiertes Schlüsselmaterial muss genau dem ursprünglichen Schlüsselmaterial entsprechen, wenn die Version zuvor erfolgreich importiert wurde.
  • CryptoKeyVersions, die vor dem Release dieses Features gelöscht wurden, können nicht noch einmal importiert werden. Das Feld reimport_eligible der CryptoKeyVersion ist true, wenn die Version für einen erneuten Import infrage kommt, und false, wenn dies nicht der Fall ist.

Software- und Cloud HSM-Schlüssel können noch einmal importiert werden, externe Schlüssel jedoch nicht.

Einen gelöschten Schlüssel noch einmal importieren

Erstellen Sie einen ImportJob für den erneuten Import. Folgen Sie dazu den Schritten unter Importjob erstellen. Sie können entweder einen vorhandenen ImportJob oder einen neuen ImportJob verwenden, solange das Schutzniveau dem ursprünglichen Schutzniveau entspricht.

Console

  1. Rufen Sie in der Google Cloud Console die Seite Schlüsselverwaltung auf.

    Zur Seite „Schlüsselverwaltung“

  2. Klicken Sie auf den Namen des Schlüsselbunds mit dem Schlüssel, dessen Schlüsselversion Sie noch einmal importieren möchten.

  3. Klicken Sie auf den Schlüssel, dessen Schlüsselversion Sie noch einmal importieren möchten.

  4. Klicken Sie auf die drei Punkte neben der Schlüsselversion, die Sie noch einmal importieren möchten.

  5. Wählen Sie Schlüsselversion neu importieren.

  6. Wählen Sie den Importjob aus dem Drop-down-Menü Importjob auswählen aus.

  7. Wählen Sie aus der Auswahl Verpackten Schlüssel hochladen den Schlüssel aus, den Sie bereits verpackt haben. Dieser Schlüssel muss dem ursprünglichen Schlüsselmaterial entsprechen.

  8. Klicken Sie auf Neu importieren.

gcloud

Wenn Sie Cloud KMS in der Befehlszeile verwenden möchten, müssen Sie zuerst die neueste Version der Google Cloud CLI installieren oder ein Upgrade auf die neueste Version durchführen.

  1. Importieren Sie die Schlüsselversion mit dem ursprünglichen Schlüsselmaterial neu.

    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

In diesen Beispielen wird curl als HTTP-Client verwendet, um die Verwendung der API zu demonstrieren. Weitere Informationen zur Zugriffssteuerung finden Sie unter Auf die Cloud KMS API zugreifen.

  1. Legen Sie im Anfragetext der cryptoKeyVersions.import-Methode das cryptoKeyVersion-Feld auf den Namen der Schlüsselversion der zu importierenden Version fest. Dies muss ein untergeordnetes Element des kryptografischen Schlüssels sein.

  2. Setzen Sie im Anfragetext das algorithm-Feld auf den Algorithmus des zu importierenden Schlüssels fest. Dieser Wert muss dem Algorithmus der ursprünglichen Schlüsselversion entsprechen. Das Feld algorithm hat den Typ CryptoKeyVersionAlgorithm.

  3. Legen Sie im Anfragetext im wrappedKeyMaterial-Feld das Schlüsselmaterial fest, das Sie bereits verpackt haben.

  4. Rufen Sie die Methode cryptoKeyVersions.import auf. Die Antwort cryptoKeyVersions.import hat den Typ CryptoKeyVersion. Wurde ein Schlüssel erfolgreich importiert, lautet der Status ENABLED und Sie können ihn in Cloud KMS verwenden.

Nächste Schritte

Zurück
Automatisches Key-Wrapping einrichten
Weiter
Importierte Schlüsselversion prüfen