Quantensicherer Schlüsselimport

In dieser Anleitung wird beschrieben, wie Sie einen kryptografischen Schlüssel als neue Schlüsselversion mit einer quantensicheren Importmethode in Cloud Key Management Service importieren. Dieser Ansatz trägt dazu bei, den Schlüssel während der Übertragung vor „Jetzt speichern, später entschlüsseln“-Angriffen (HNDL) durch zukünftige Quantencomputer zu schützen.

Beim quantensicheren Schlüsselimport werden standardmäßige Post-Quanten-Kryptografie-Tools (PQC) verwendet, darunter Key Encapsulation Mechanisms (KEMs) und Hybrid Public Key Encryption (HPKE), um Ihren Schlüssel während der Übertragung zu schützen.

Der Import quantensicherer Schlüssel wird für softwaregestützte Schlüssel (Schutzniveau SOFTWARE) unterstützt.

Hinweis

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

Projekt vorbereiten

1. In the Cloud de Confiance console, on the project selector page, select or create a Cloud de Confiance project.

   Roles required to select or create a project

   • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
   • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

   Go to project selector

2. Verify that billing is enabled for your Cloud de Confiance project.

3. Enable the required API.

   Roles required to enable APIs

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

   Enable the API

4. Installieren Sie die Google Cloud CLI.

5. Konfigurieren Sie die gcloud CLI für die Verwendung Ihrer föderierten Identität.

   Weitere Informationen finden Sie unter Mit Ihrer föderierten Identität in der gcloud CLI anmelden.

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

   gcloud init

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für den Schlüsselbund zuzuweisen, damit Sie die nötigen Berechtigungen zum Importieren eines Schlüssels haben:

• Nur in vorhandene Schlüssel importieren: Cloud KMS-Importeur (roles/cloudkms.importer)
• Für den Import in neue Schlüssel: Cloud KMS-Administrator (roles/cloudkms.admin)

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

Lokales System vorbereiten

Sie benötigen eine kryptografische Bibliothek auf Ihrem lokalen System, die Tools für die Post-Quanten-Kryptografie (Post-Quantum Cryptography, PQC) unterstützt, einschließlich Key Encapsulation Mechanisms (KEMs) und Hybrid Public Key Encryption (HPKE). Sie können Tink, OpenSSL oder eine andere Kryptografiebibliothek verwenden, die Folgendes unterstützt:

• Hybrid Public Key Encryption (HPKE)
• Einer der folgenden KEM-Algorithmen:
  • ML-KEM-768
  • ML-KEM-1024
  • X-WING (eine Mischung aus ML-KEM-768 und X25519)
• Die Schlüsselableitungsfunktion (Key Derivation Function, KDF) HKDF-SHA256
• Authentifizierte Verschlüsselung mit verknüpften Daten (Authenticated Encryption with Associated Data, AEAD) mit dem AES-256-GCM-Algorithmus

Schlüssel vorbereiten

Prüfen Sie, ob Algorithmus und Länge Ihres Schlüssels unterstützt werden. Alle Versionen eines Schlüssels müssen dasselbe Schutzniveau (SOFTWARE) haben.

Den Zielschlüssel und Schlüsselbund erstellen

Wenn Sie Schlüsselmaterial importieren, wird es zu einer neuen Schlüsselversion eines vorhandenen Schlüssels. Dieser Schlüssel wird als Zielschlüssel bezeichnet. Der Zielschlüsselbund und der Zielschlüssel müssen vorhanden sein, bevor Sie Schlüsselmaterial importieren können.

Mit den unten aufgeführten Schritten können Sie einen leeren, softwarebasierten Schlüssel für einen neuen Schlüsselbund mit der Google Cloud CLI oder der Cloud de Confiance -Konsole erstellen.

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 des Schutzniveaus und der Importmethode.

Der Import von quantensicheren Schlüsseln wird nur für das Schutzniveau SOFTWARE unterstützt. Wählen Sie eine der folgenden quantensicheren Importmethoden aus:

• HPKE_KEM_XWING_HKDF_SHA256_AES_256_GCM
• HPKE_KEM_ML_KEM_768_HKDF_SHA256_AES_256_GCM

• HPKE_KEM_ML_KEM_1024_HKDF_SHA256_AES_256_GCM

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

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

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 mit der Google Cloud CLI, derCloud de Confiance -Konsole oder der Cloud Key Management Service API überprüfen.

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

state: ACTIVE

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
}

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());
    }
  }
}

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

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

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.

Öffentlichen Verpackungsschlüssel abrufen

Nachdem der Importjob ACTIVE ist, rufen Sie den zugehörigen öffentlichen Schlüssel ab. Sie verwenden diesen öffentlichen Schlüssel auf Ihrem lokalen System, um das zu importierende Schlüsselmaterial zu verpacken.

gcloud kms import-jobs describe IMPORT_JOB 

    --location LOCATION 

    --keyring KEY_RING 

    --format="value(publicKey.data)"

Schlüsselmaterial vorbereiten und verpacken

Verwenden Sie eine unterstützte externe kryptografische Bibliothek auf Ihrem lokalen System, um das Schlüsselmaterial mit dem abgerufenen öffentlichen Verpackungsschlüssel zu verpacken.

Beim Wrapping-Vorgang muss HPKE.Seal() (RFC 9180) ausgeführt werden, um einen verpackten Schlüssel zu erstellen. Damit sind die folgenden Schritte abgeschlossen:

1. Kapseln Sie den abgerufenen öffentlichen Schlüssel, um einen gemeinsamen Schlüssel und einen Kapselungsschlüssel zu erstellen.
2. Leiten Sie mit HKDF-SHA256 einen temporären symmetrischen Schlüssel aus dem gemeinsamen Secret ab.
3. Verschlüsseln Sie Ihr Schlüsselmaterial mit dem temporären Schlüssel mit AES‑256‑GCM.
4. Verketten Sie den Kapselungsschlüssel und das als Geheimtext verschlüsselte Schlüsselmaterial. Dies ist der resultierende verpackte Schlüssel, den Sie zum Importieren des Schlüssels verwenden. Speichern Sie die Datei als wrapped_key.bin.

Das folgende Go-Codebeispiel zeigt, wie Schlüsselmaterial mit der tink-go-Bibliothek umschlossen wird:

package main

import (
    "bytes"
    "encoding/base64"
    "flag"
    "fmt"
    "log"

    "google.golang.org/protobuf/proto"
    "github.com/tink-crypto/tink-go/v2/hybrid"
    "github.com/tink-crypto/tink-go/v2/keyset"

    hpkepb "github.com/tink-crypto/tink-go/v2/proto/hpke_go_proto"
    tinkpb "github.com/tink-crypto/tink-go/v2/proto/tink_go_proto"
)

var (
    publicKeyB64Flag = flag.String("public_key", "", "Base64 encoded public key for wrapping.")
    targetKeyB64Flag = flag.String("target_key", "", "Base64 encoded 32-byte target key to be wrapped.")
)

func main() {
    flag.Parse()

    if *publicKeyB64Flag == "" {
        log.Fatal("-public_key is required")
    }
    if *targetKeyB64Flag == "" {
        log.Fatal("-target_key is required")
    }

    pkBytes, err := base64.StdEncoding.DecodeString(*publicKeyB64Flag)
    if err != nil {
        log.Fatalf("failed to decode public key: %v", err)
    }

    targetKey, err := base64.StdEncoding.DecodeString(*targetKeyB64Flag)
    if err != nil {
        log.Fatalf("failed to decode target key: %v", err)
    }

    hpkePubKey := &hpkepb.HpkePublicKey{
        Version: 0,
        Params: &hpkepb.HpkeParams{
            Kem:  hpkepb.HpkeKem_ML_KEM768,
            Kdf:  hpkepb.HpkeKdf_HKDF_SHA256,
            Aead: hpkepb.HpkeAead_AES_256_GCM,
        },
        PublicKey: pkBytes,
    }
    serializedPubKey, err := proto.Marshal(hpkePubKey)
    if err != nil {
        log.Fatalf("failed to marshal HPKE public key: %v", err)
    }

    ks := &tinkpb.Keyset{
        PrimaryKeyId: 1,
        Key: []*tinkpb.Keyset_Key{
            {
                KeyData: &tinkpb.KeyData{
                    TypeUrl:         "type.googleapis.com/google.crypto.tink.HpkePublicKey",
                    Value:           serializedPubKey,
                    KeyMaterialType: tinkpb.KeyData_ASYMMETRIC_PUBLIC,
                },
                Status:           tinkpb.KeyStatusType_ENABLED,
                KeyId:            1,
                OutputPrefixType: tinkpb.OutputPrefixType_RAW,
            },
        },
    }
    serializedKeyset, err := proto.Marshal(ks)
    if err != nil {
        log.Fatalf("failed to marshal keyset: %v", err)
    }

    // Create a KeysetHandle and retrieve the HybridEncrypt primitive.
    reader := keyset.NewBinaryReader(bytes.NewReader(serializedKeyset))
    handle, err := keyset.ReadWithNoSecrets(reader)
    if err != nil {
        log.Fatalf("failed to create keyset handle: %v", err)
    }

    enc, err := hybrid.NewHybridEncrypt(handle)
    if err != nil {
        log.Fatalf("failed to create hybrid encrypt primitive: %v", err)
    }

    // Perform the wrapping operation. Tink's HPKE implementation handles the
  // 'enc || ciphertext' concatenation automatically.
    wrappedKey, err := enc.Encrypt(targetKey, nil)
    if err != nil {
        log.Fatalf("failed to wrap key: %v", err)
    }

    fmt.Printf("Final wrappedKey (base64):\n%s\n", base64.StdEncoding.EncodeToString(wrappedKey))
}

Speichern Sie den Base64-Ausgabestring oder decodieren Sie ihn in eine Binärdatei: bash echo "BASE64_WRAPPED_KEY" | base64 --decode > wrapped_key.bin

Verpackten Schlüssel importieren

Importieren Sie den vorbereiteten verpackten Schlüssel als neue Schlüsselversion Ihres Zielschlüssels.

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

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

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, lautet der Status IMPORT_FAILED.

Sie können den Status einer Importanfrage mit der Google Cloud CLI, derCloud de Confiance -Konsole oder der Cloud Key Management Service API überprüfen.

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

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
}

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());
    }
  }
}

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

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

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

Einen gelöschten Schlüssel noch einmal importieren

Wenn Sie eine zuvor importierte Schlüsselversion mit dem Status DESTROYED oder IMPORT_FAILED wiederherstellen und in den Status ENABLED zurücksetzen möchten, können Sie genau dasselbe Schlüsselmaterial noch einmal importieren.

Für den Neuimport einer zerstörten Schlüsselversion wird dasselbe Verfahren wie beim ursprünglichen Import verwendet. Dabei kann entweder der ursprüngliche oder ein neuer Importjob (mit derselben Schutzstufe SOFTWARE) verwendet werden.