Impor kunci quantum-safe

Panduan ini menunjukkan cara mengimpor kunci kriptografis ke Cloud Key Management Service sebagai versi kunci baru menggunakan metode impor quantum-safe. Pendekatan ini membantu melindungi kunci selama pengiriman dari serangan "simpan sekarang, dekripsi nanti" (SNDL) oleh komputer kuantum di masa mendatang.

Impor kunci quantum-safe menggunakan alat post-quantum cryptography (PQC) standar, termasuk mekanisme enkapsulasi kunci (KEM) dan enkripsi kunci publik hibrid (HPKE) untuk melindungi kunci Anda saat dalam pengiriman.

Impor kunci quantum-safe didukung untuk kunci yang didukung software (tingkat perlindungan SOFTWARE).

Sebelum memulai

Sebelum dapat mengimpor kunci, Anda harus menyiapkan project, sistem lokal, dan materi kunci itu sendiri.

Menyiapkan project

  1. Login ke akun Google Cloud Anda. Jika Anda baru menggunakan Google Cloud, buat akun untuk mengevaluasi performa produk kami dalam skenario dunia nyata. Pelanggan baru juga mendapatkan kredit gratis senilai $300 untuk menjalankan, menguji, dan men-deploy workload.

  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 role (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, if it is not already enabled.

    Roles required to enable APIs

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

    Enable the API

  5. Install the Google Cloud CLI.

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

  7. To initialize the gcloud CLI, run the following command: 

    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 role (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, if it is not already enabled.

    Roles required to enable APIs

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

    Enable the API

  11. Install the Google Cloud CLI.

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

  13. To initialize the gcloud CLI, run the following command: 

    gcloud init

Peran yang diperlukan

Untuk mendapatkan izin yang Anda perlukan untuk mengimpor kunci, minta administrator untuk memberi Anda peran IAM berikut pada ring kunci:

Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.

Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Menyiapkan sistem lokal

Anda memerlukan library kriptografi di sistem lokal yang mendukung alat kriptografi pasca-kuantum (PQC), termasuk mekanisme enkapsulasi kunci (KEM) dan enkripsi kunci publik hibrid (HPKE). Anda dapat menggunakan Tink, OpenSSL, atau library kriptografi lain yang mendukung hal berikut:

  • Enkripsi kunci publik hibrida (HPKE)
  • Salah satu algoritma KEM berikut:
    • ML-KEM-768
    • ML-KEM-1024
    • X-WING (gabungan ML-KEM-768 dan X25519)
  • Fungsi derivasi kunci (KDF) HKDF-SHA256
  • Enkripsi terautentikasi dengan data terkait (AEAD) menggunakan algoritma AES-256-GCM

Siapkan kunci

Pastikan algoritma dan panjang kunci Anda didukung. Semua versi kunci harus memiliki tingkat perlindungan yang sama (SOFTWARE).

Membuat kunci penargetan dan key ring

Saat Anda mengimpor materi kunci, materi tersebut akan menjadi versi kunci baru pada kunci yang ada. Kunci ini disebut kunci penargetan. Key ring target dan kunci target harus ada sebelum Anda dapat mengimpor materi kunci.

Ikuti langkah-langkah berikut untuk membuat kunci kosong yang didukung software pada key ring baru menggunakan Google Cloud CLI atau konsol Google Cloud .

Konsol

  1. Di konsol Google Cloud , buka halaman Key Management.

    Buka Key Management

  2. Klik Create key ring.

  3. Di kolom Key ring name, masukkan nama untuk key ring.

  4. Di bagian Location type, pilih jenis lokasi dan lokasi.

  5. Klik Create. Halaman Buat kunci akan terbuka.

  6. Di kolom Key name, masukkan nama untuk kunci Anda.

  7. Untuk Protection level, pilih Software.

  8. Untuk Key material, pilih Imported key, lalu klik Continue. Tindakan ini mencegah pembuatan versi kunci awal.

  9. Tetapkan Purpose dan Algorithm untuk kunci, lalu klik Continue.

  10. Opsional: Jika Anda ingin kunci ini hanya berisi versi kunci yang diimpor, pilih Restrict key versions to import only. Hal ini mencegah Anda membuat versi kunci baru secara tidak sengaja di Cloud KMS.

  11. Opsional: Untuk kunci yang diimpor, rotasi otomatis dinonaktifkan secara default. Untuk mengaktifkan rotasi kunci otomatis, pilih nilai dari kolom Key rotation period.

    Jika Anda mengaktifkan rotasi otomatis, versi kunci baru akan dibuat di Cloud KMS, dan versi kunci yang diimpor tidak akan lagi menjadi versi kunci default setelah rotasi.

  12. Klik Create.

gcloud

Untuk menggunakan Cloud KMS di command line, pertama-tama Instal atau upgrade ke Google Cloud CLI versi terbaru.

  1. Buat key ring target. Pilih lokasi yang kompatibel dengan tingkat perlindungan yang ingin Anda gunakan. Untuk mengetahui informasi selengkapnya tentang lokasi yang didukung, lihat lokasi Cloud KMS.

    gcloud kms keyrings create KEY_RING \
  --location LOCATION

    Anda dapat mempelajari lebih lanjut cara membuat key ring.

  2. Buat kunci target menggunakan perintah kms keys create dengan flag --skip-initial-version-creation. Tindakan ini akan membuat kunci tanpa versi kunci awal sehingga materi kunci yang Anda impor adalah versi 1. Gunakan flag --import-only untuk mencegah Cloud KMS membuat materi kunci untuk versi kunci baru. Jika tanda ini disetel, versi kunci baru untuk kunci ini harus diimpor. Kunci yang dibuat sebagai --import-only harus dirotasi secara manual.

    gcloud kms keys create KEY_NAME \
  --location LOCATION \
  --keyring KEY_RING \
  --purpose PURPOSE \
  --protection-level SOFTWARE \
  --skip-initial-version-creation \
  --import-only

    Ganti kode berikut:

    • KEY_NAME: nama yang ingin Anda gunakan untuk kunci.
    • LOCATION: lokasi key ring.
    • KEY_RING: key ring tempat Anda ingin membuat kunci.
    • PURPOSE: tujuan yang ingin Anda gunakan untuk kunci.

API

Contoh ini menggunakan curl sebagai klien HTTP untuk menunjukkan penggunaan API. Untuk mengetahui informasi selengkapnya tentang kontrol akses, lihat Mengakses Cloud KMS API.

  1. Buat key ring baru:

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

    Lihat dokumentasi KeyRing.create API untuk mengetahui informasi selengkapnya.

  2. Buat kunci kosong hanya untuk impor:

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

    Lihat dokumentasi CryptoKey.create API untuk mengetahui informasi selengkapnya.

Key ring dan kunci kini ada, tetapi kunci tidak berisi materi kunci, tidak memiliki versi, dan tidak aktif. Selanjutnya, Anda membuat tugas impor.

Membuat tugas impor

Tugas impor menentukan karakteristik kunci yang diimpor, termasuk tingkat perlindungan dan metode impor.

Impor kunci quantum-safe hanya didukung untuk tingkat perlindungan SOFTWARE. Pilih salah satu metode impor quantum-safe berikut:

  • 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

Jalankan perintah berikut untuk membuat tugas impor dengan metode impor yang quantum-safe:

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

Ganti kode berikut:

  • IMPORT_JOB: nama unik yang akan digunakan untuk tugas impor.
  • LOCATION: lokasi key ring tempat Anda membuat kunci penargetan.
  • KEY_RING: nama key ring tempat Anda membuat kunci target.
  • IMPORT_METHOD: metode impor quantum-safe yang ingin Anda gunakan—misalnya, hpke-kem-xwing-hkdf-sha256-aes-256-gcm.

REST

Panggil metode keyRings.importJobs.create:

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

Ganti kode berikut:

  • PROJECT_ID: ID project Cloud KMS Anda.
  • LOCATION: lokasi key ring tempat Anda membuat kunci penargetan.
  • KEY_RING: nama key ring tempat Anda membuat kunci target.
  • IMPORT_JOB: nama unik yang akan digunakan untuk tugas impor.
  • TOKEN: token untuk mengautentikasi permintaan.
  • IMPORT_METHOD: metode impor quantum-safe yang ingin Anda gunakan—misalnya, HPKE_KEM_XWING_HKDF_SHA256_AES_256_GCM.

Memeriksa status tugas impor

Status awal untuk tugas impor adalah PENDING_GENERATION. Jika statusnya ACTIVE, Anda dapat menggunakannya untuk mengimpor kunci.

Tugas impor akan berakhir setelah tiga hari. Jika tugas impor sudah tidak berlaku, Anda harus membuat tugas baru.

Anda dapat memeriksa status tugas impor menggunakan Google Cloud CLI, konsolGoogle Cloud , atau Cloud Key Management Service API.

Konsol

  1. Di konsol Google Cloud , buka halaman Key Management.

    Buka Key Management

  2. Klik nama key ring yang berisi tugas impor Anda.

  3. Klik tab Tugas Impor di bagian atas halaman.

  4. Status akan terlihat di bagian Status di samping nama tugas impor Anda.

gcloud

Untuk menggunakan Cloud KMS di command line, pertama-tama Instal atau upgrade ke Google Cloud CLI versi terbaru.

Saat tugas impor aktif, Anda dapat menggunakannya untuk mengimpor kunci. Proses ini mungkin memerlukan waktu beberapa menit. Gunakan perintah ini untuk memverifikasi bahwa tugas impor sedang aktif. Gunakan lokasi dan keyring tempat Anda membuat tugas impor.

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

Outputnya mirip dengan hal berikut ini:

state: ACTIVE

Go

Untuk menjalankan kode ini, siapkan lingkungan pengembangan Go terlebih dahulu dan instal Cloud KMS Go SDK.

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

Untuk menjalankan kode ini, pertama-tama siapkan lingkungan pengembangan Java dan instal Cloud KMS Java SDK.

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

Untuk menjalankan kode ini, pertama-tama siapkan lingkungan pengembangan Node.js dan instal 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

Untuk menjalankan kode ini, siapkan lingkungan pengembangan Python terlebih dahulu dan instal Cloud KMS Python SDK.

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

Contoh ini menggunakan curl sebagai klien HTTP untuk menunjukkan penggunaan API. Untuk mengetahui informasi selengkapnya tentang kontrol akses, lihat Mengakses Cloud KMS API.

Untuk memeriksa status tugas impor, gunakan metode 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"

Segera setelah tugas impor aktif, Anda dapat mengimpor kunci.

Mengambil kunci pelapis publik

Setelah tugas impor ACTIVE, ambil kunci publik yang terkait dengannya. Anda akan menggunakan kunci publik ini di sistem lokal untuk melapis materi kunci yang ingin Anda impor.

gcloud

Jalankan perintah berikut untuk mendownload kunci publik:

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

Ganti kode berikut:

  • IMPORT_JOB: nama tugas impor.
  • LOCATION: lokasi key ring tempat Anda membuat tugas impor.
  • KEY_RING: nama key ring tempat Anda membuat tugas impor.

Kunci publik dienkode dengan base64.

REST

  1. Panggil metode keyRings.importJobs.get.
  2. Ambil kunci publik dari kolom publicKey.data respons, dan simpan secara lokal sebagai public_key.data.

Menyiapkan dan melapis materi kunci Anda

Gunakan library kriptografis eksternal yang didukung di sistem lokal Anda untuk menggabungkan materi kunci menggunakan kunci penggabungan publik yang diambil.

Proses wrapping harus melakukan HPKE.Seal() (RFC 9180) untuk menghasilkan kunci yang di-wrap. Langkah-langkah berikut telah selesai:

  1. Enkapsulasi kunci publik yang diambil untuk menghasilkan rahasia bersama dan kunci enkapsulasi.
  2. Dapatkan kunci simetris sementara dari rahasia bersama menggunakan HKDF-SHA256.
  3. Enkripsi materi kunci Anda dengan kunci sementara menggunakan AES-256-GCM.
  4. Gabungkan kunci enkapsulasi dan materi kunci yang dienkripsi sebagai ciphertext. Ini adalah kunci gabungan yang dihasilkan yang akan Anda gunakan untuk mengimpor kunci. Simpan ini sebagai wrapped_key.bin.

Contoh kode Go berikut menunjukkan penggabungan materi kunci menggunakan library tink-go:

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

Simpan string base64 output atau dekode ke file biner: bash echo "BASE64_WRAPPED_KEY" | base64 --decode > wrapped_key.bin

Mengimpor kunci gabungan

Impor kunci gabungan yang telah disiapkan sebagai versi kunci baru dari kunci target Anda.

gcloud

Jalankan perintah kms keys versions import:

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

Ganti kode berikut:

  • LOCATION: lokasi key ring yang berisi kunci penargetan Anda.
  • KEY_RING: nama key ring yang berisi kunci target Anda.
  • KEY_NAME: nama kunci penargetan Anda.
  • IMPORT_JOB: nama tugas impor Anda.
  • ALGORITHM: algoritma materi kunci yang akan diimpor.

REST

Panggil metode cryptoKeyVersions.import:

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

Ganti kode berikut:

  • PROJECT_ID: ID project Cloud KMS Anda.
  • LOCATION: lokasi key ring yang berisi kunci penargetan Anda.
  • KEY_RING: nama key ring yang berisi kunci target Anda.
  • KEY_NAME: nama kunci penargetan Anda.
  • TOKEN: token untuk mengautentikasi permintaan.
  • IMPORT_JOB: ID tugas impor yang sesuai.
  • ALGORITHM: algoritma materi kunci yang akan diimpor.
  • PATH_TO_WRAPPED_KEY: jalur ke kunci yang digabungkan secara manual dalam format base64.

Periksa status versi kunci yang diimpor

Status awal untuk versi kunci yang diimpor adalah PENDING_IMPORT. Jika statusnya adalah ENABLED, versi kunci telah berhasil diimpor. Jika impor gagal, statusnya adalah IMPORT_FAILED.

Anda dapat memeriksa status permintaan impor menggunakan Google Cloud CLI, konsolGoogle Cloud , atau Cloud Key Management Service API.

Konsol

  1. Di konsol Google Cloud , buka halaman Key Management.

    Buka Key Management

  2. Klik nama key ring yang berisi tugas impor Anda.

  3. Klik tab Tugas Impor di bagian atas halaman.

  4. Status akan terlihat di bagian Status di samping nama tugas impor Anda.

gcloud

Untuk menggunakan Cloud KMS di command line, Instal atau upgrade ke versi terbaru Google Cloud CLI terlebih dahulu.

Gunakan perintah versions list untuk memeriksa status. Gunakan lokasi, target key ring, dan target kunci yang sama yang Anda buat sebelumnya dalam topik ini.

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

Go

Untuk menjalankan kode ini, pertama-tama siapkan lingkungan pengembangan Go dan instal Cloud KMS Go SDK.

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

Untuk menjalankan kode ini, pertama-tama siapkan lingkungan pengembangan Java dan instal Cloud KMS Java SDK.

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

Untuk menjalankan kode ini, pertama-tama siapkan lingkungan pengembangan Node.js dan instal 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

Untuk menjalankan kode ini, pertama-tama siapkan lingkungan pengembangan Python dan instal Cloud KMS Python SDK.

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

Contoh ini menggunakan curl sebagai klien HTTP untuk menunjukkan penggunaan API. Untuk mengetahui informasi selengkapnya tentang kontrol akses, lihat Mengakses Cloud KMS API.

Panggil metode ImportJob.get dan periksa kolom [state][api_importjob_fields_state]. Jika state adalah PENDING_GENERATION, tugas impor masih dibuat. Periksa kembali status secara berkala hingga menjadi ACTIVE.

Setelah versi kunci awal diimpor, status kunci akan berubah menjadi ENABLED. Untuk kunci simetris, Anda harus menetapkan versi kunci yang diimpor sebagai versi utama sebelum dapat menggunakan kunci tersebut.

Mengimpor ulang kunci yang sebelumnya dihancurkan

Jika perlu memulihkan versi kunci yang sebelumnya diimpor yang berada dalam status DESTROYED atau IMPORT_FAILED kembali ke status ENABLED, Anda dapat mengimpor ulang materi kunci yang sama persis.

Mengimpor ulang versi kunci yang dihancurkan menggunakan prosedur yang sama dengan impor awal, menggunakan tugas impor asli atau tugas impor baru (dengan tingkat perlindungan SOFTWARE yang sama).

Sebelumnya
Menggabungkan kunci menggunakan OpenSSL
Berikutnya
Menyiapkan penggabungan kunci otomatis