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 transit dari serangan "kumpulkan sekarang, dekripsi nanti" (HNDL) oleh komputer kuantum di masa mendatang.
Impor kunci yang aman dari serangan kuantum menggunakan alat kriptografi post-quantum (PQC) standar, termasuk mekanisme enkapsulasi kunci (KEM) dan enkripsi kunci publik hibrida (HPKE) untuk melindungi kunci Anda selama 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
-
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 theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Cloud de Confiance project.
Enable the required API.
Roles required to enable APIs
To enable APIs, you need the
serviceusage.services.enablepermission. 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.-
Instal Google Cloud CLI.
-
Konfigurasi gcloud CLI agar menggunakan identitas gabungan Anda.
Untuk mengetahui informasi selengkapnya, lihat Login ke gcloud CLI dengan identitas gabungan Anda.
-
Untuk melakukan inisialisasi gcloud CLI, jalankan perintah berikut:
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 mengimpor hanya ke kunci yang ada:
Cloud KMS Importer (
roles/cloudkms.importer) -
Untuk mengimpor ke kunci baru:
Admin Cloud KMS (
roles/cloudkms.admin)
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 hibrida (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-768ML-KEM-1024X-WING(gabungan dariML-KEM-768danX25519)
- Fungsi derivasi kunci (KDF)
HKDF-SHA256 - Enkripsi yang diautentikasi 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).
Buat kunci target dan key ring
Saat Anda mengimpor materi kunci, materi kunci tersebut akan menjadi versi kunci baru pada kunci yang ada. Kunci ini disebut kunci target. Target key ring dan target kunci harus ada sebelum Anda dapat mengimpor materi kunci.
Ikuti langkah-langkah berikut untuk membuat kunci kosong yang didukung software di ring kunci baru menggunakan Google Cloud CLI atau konsol Cloud de Confiance .
Konsol
Di konsol Cloud de Confiance , buka halaman Key Management.
Klik Create key ring.
Di kolom Key ring name, masukkan nama untuk key ring.
Di bagian Jenis lokasi, pilih jenis lokasi dan lokasi.
Klik Create. Halaman Buat kunci akan terbuka.
Di kolom Key name, masukkan nama untuk kunci Anda.
Untuk Tingkat perlindungan, pilih Software.
Untuk Key material, pilih Imported key, lalu klik Continue. Tindakan ini mencegah pembuatan versi kunci awal.
Tetapkan Tujuan dan Algoritma untuk kunci, lalu klik Lanjutkan.
Opsional: Jika Anda ingin kunci ini hanya berisi versi kunci yang diimpor, pilih Batasi versi kunci hanya untuk impor. Hal ini mencegah Anda secara tidak sengaja membuat versi kunci baru di Cloud KMS.
Opsional: Untuk kunci yang diimpor, rotasi otomatis dinonaktifkan secara default. Untuk mengaktifkan rotasi otomatis, pilih nilai dari kolom Periode rotasi kunci.
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.
Klik Create.
gcloud
Untuk menggunakan Cloud KMS di command line, Instal atau upgrade ke versi terbaru Google Cloud CLI terlebih dahulu.
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.
Buat kunci target menggunakan perintah
kms keys createdengan flag--skip-initial-version-creation. Tindakan ini akan membuat kunci tanpa versi kunci awal sehingga materi kunci yang diimpor adalah versi1. Gunakan flag--import-onlyuntuk mencegah Cloud KMS membuat materi kunci untuk versi kunci baru. Dengan setelan flag ini, versi kunci baru untuk kunci ini harus diimpor. Kunci yang dibuat sebagai--import-onlyharus dirotasi secara manual.gcloud kms keys create KEY_NAME \ --location LOCATION \ --keyring KEY_RING \ --purpose PURPOSE \ --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.
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 API
KeyRing.createuntuk mengetahui informasi selengkapnya.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 API
CryptoKey.createuntuk 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.
Buat tugas impor
Tugas impor menentukan karakteristik kunci yang diimpornya, 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_GCMHPKE_KEM_ML_KEM_768_HKDF_SHA256_AES_256_GCMHPKE_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 target.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 target.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.
Periksa status tugas impor
Status awal untuk tugas impor adalah PENDING_GENERATION. Jika statusnya adalah
ACTIVE, Anda dapat menggunakannya untuk mengimpor kunci.
Masa berlaku tugas impor akan berakhir setelah tiga hari. Jika masa berlaku tugas impor telah berakhir, Anda harus membuat tugas baru.
Anda dapat memeriksa status tugas impor menggunakan Google Cloud CLI, konsolCloud de Confiance , atau Cloud Key Management Service API.
Konsol
Buka halaman Key Management di konsol Cloud de Confiance .
Klik nama key ring yang berisi tugas impor Anda.
Klik tab Pekerjaan Impor di bagian atas halaman.
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.
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.
Java
Untuk menjalankan kode ini, siapkan lingkungan pengembangan Java terlebih dahulu dan instal Cloud KMS Java SDK.
Node.js
Untuk menjalankan kode ini, siapkan lingkungan pengembangan Node.js terlebih dahulu dan instal Cloud KMS Node.js SDK.
Python
Untuk menjalankan kode ini, siapkan lingkungan pengembangan Python terlebih dahulu dan instal Cloud KMS Python SDK.
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 membuat permintaan untuk mengimpor kunci.
Mengambil kunci pembungkus 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
- Panggil metode
keyRings.importJobs.get. - Ambil kunci publik dari kolom
publicKey.datarespons, dan simpan secara lokal sebagaipublic_key.data.
Siapkan dan bungkus materi utama Anda
Gunakan library kriptografi eksternal yang didukung di sistem lokal Anda untuk mengenkapsulasi materi kunci menggunakan kunci pelapis publik yang diambil.
Proses wrapping harus melakukan HPKE.Seal() (RFC 9180) untuk menghasilkan kunci yang di-wrap. Langkah-langkah berikut telah selesai:
- Enkapsulasi kunci publik yang diambil untuk menghasilkan rahasia bersama dan kunci enkapsulasi.
- Dapatkan kunci simetris sementara dari rahasia bersama menggunakan HKDF-SHA256.
- Enkripsi materi kunci Anda dengan kunci sementara menggunakan AES-256-GCM.
- Gabungkan kunci enkapsulasi dan materi kunci yang dienkripsi sebagai ciphertext. Ini adalah kunci terbungkus yang akan Anda gunakan untuk mengimpor
kunci. Simpan sebagai
wrapped_key.bin.
Contoh kode Go berikut menunjukkan pembungkusan materi utama 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
Impor kunci gabungan
Impor kunci yang digabungkan 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 target Anda.KEY_RING: nama key ring yang berisi kunci target Anda.KEY_NAME: nama kunci target 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 target Anda.KEY_RING: nama key ring yang berisi kunci target Anda.KEY_NAME: nama kunci target 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, konsolCloud de Confiance , atau Cloud Key Management Service API.
Konsol
Buka halaman Key Management di Cloud de Confiance console.
Klik nama key ring yang berisi tugas impor Anda.
Klik tab Pekerjaan Impor di bagian atas halaman.
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, siapkan lingkungan pengembangan Go terlebih dahulu dan instal Cloud KMS Go SDK.
Java
Untuk menjalankan kode ini, siapkan lingkungan pengembangan Java terlebih dahulu dan instal Cloud KMS Java SDK.
Node.js
Untuk menjalankan kode ini, siapkan lingkungan pengembangan Node.js terlebih dahulu dan instal Cloud KMS Node.js SDK.
Python
Untuk menjalankan kode ini, siapkan lingkungan pengembangan Python terlebih dahulu dan instal Cloud KMS Python SDK.
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).