Importazione di chiavi quantum-safe

Questa guida mostra come importare una chiave di crittografia in Cloud Key Management Service come nuova versione della chiave utilizzando un metodo di importazione quantum-safe. Questo approccio contribuisce a proteggere la chiave durante il transito dagli attacchi "Harvest Now, Decrypt Later" (HNDL) da parte di futuri computer quantistici.

L'importazione di chiavi quantum-safe utilizza strumenti di crittografia post-quantistica (PQC) standard, inclusi meccanismi di incapsulamento delle chiavi (KEM) e crittografia ibrida a chiave pubblica (HPKE) per proteggere la chiave durante il transito.

L'importazione di chiavi quantum-safe è supportata per le chiavi basate su software (livello di protezione SOFTWARE).

Prima di iniziare

Prima di poter importare una chiave, devi preparare il progetto, il sistema locale e il materiale della chiave.

Prepara il progetto

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

5. Configura gcloud CLI per utilizzare la tua identità federata.

   Per ulteriori informazioni, vedi Accedi a gcloud CLI con la tua identità federata.

6. Per inizializzare gcloud CLI, esegui questo comando:

   gcloud init

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per importare una chiave, chiedi all'amministratore di concederti i seguenti ruoli IAM sul portachiavi:

• Per importare solo nelle chiavi esistenti: Cloud KMS Importer (roles/cloudkms.importer)
• Per importare in nuove chiavi: Amministratore Cloud KMS (roles/cloudkms.admin)

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Preparare il sistema locale

Sul sistema locale è necessaria una libreria crittografica che supporti gli strumenti di crittografia post-quantistica (PQC), inclusi i meccanismi di incapsulamento delle chiavi (KEM) e la crittografia a chiave pubblica ibrida (HPKE). Puoi utilizzare Tink, OpenSSL o un'altra libreria di crittografia che supporti quanto segue:

• Crittografia a chiave pubblica ibrida (HPKE)
• Uno dei seguenti algoritmi KEM:
  • ML-KEM-768
  • ML-KEM-1024
  • X-WING (un ibrido di ML-KEM-768 e X25519)
• La funzione di derivazione della chiave (KDF) HKDF-SHA256
• Crittografia autenticata con dati associati (AEAD) utilizzando l'algoritmo AES-256-GCM

Prepara la chiave

Verifica che l'algoritmo e la lunghezza della chiave siano supportati. Tutte le versioni di una chiave devono avere lo stesso livello di protezione (SOFTWARE).

Crea la chiave di destinazione e le chiavi automatizzate

Quando importi il materiale della chiave, questo diventa una nuova versione della chiave esistente. Questa chiave è chiamata chiave di destinazione. Il keyring di destinazione e la chiave di destinazione devono esistere prima di poter importare il materiale della chiave.

Segui questi passaggi per creare una chiave supportata dal software vuota su un nuovo portachiavi utilizzando Google Cloud CLI o la console Cloud de Confiance .

Il keyring e la chiave ora esistono, ma la chiave non contiene materiale della chiave, non ha versioni e non è attiva. A questo punto, crea un job di importazione.

Crea il job di importazione

Un job di importazione definisce le caratteristiche delle chiavi che importa, inclusi il livello di protezione e il metodo di importazione.

L'importazione di chiavi quantum-safe è supportata solo per il livello di protezione SOFTWARE. Scegli uno dei seguenti metodi di importazione quantum-safe:

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

Controllare lo stato del job di importazione

Lo stato iniziale di un job di importazione è PENDING_GENERATION. Quando lo stato è ACTIVE, puoi utilizzarlo per importare le chiavi.

Un job di importazione scade dopo tre giorni. Se il job di importazione è scaduto, devi crearne uno nuovo.

Puoi controllare lo stato di un job di importazione utilizzando Google Cloud CLI, la consoleCloud de Confiance o l'API Cloud Key Management Service.

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"

Non appena il job di importazione è attivo, puoi inviare una richiesta di importazione di una chiave.

Recupera la chiave pubblica di wrapping

Una volta completato il job di importazione ACTIVE, recupera la chiave pubblica associata. Utilizzerai questa chiave pubblica sul tuo sistema locale per eseguire il wrapping del materiale della chiave che vuoi importare.

gcloud kms import-jobs describe IMPORT_JOB 

    --location LOCATION 

    --keyring KEY_RING 

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

Preparare e eseguire il wrapping del materiale delle chiavi

Utilizza una libreria crittografica esterna supportata sul sistema locale per eseguire il wrapping del materiale della chiave utilizzando la chiave di wrapping pubblica recuperata.

Il processo di wrapping deve eseguire HPKE.Seal() (RFC 9180) per produrre una chiave wrapped. In questo modo, vengono completati i seguenti passaggi:

1. Incapsula la chiave pubblica recuperata per produrre un segreto condiviso e una chiave di incapsulamento.
2. Deriva una chiave simmetrica temporanea dal segreto condiviso utilizzando HKDF-SHA256.
3. Cripta il materiale della chiave con la chiave effimera utilizzando AES-256-GCM.
4. Concatenare la chiave di incapsulamento e il materiale della chiave crittografato come testo crittografato. Questa è la chiave con wrapping risultante che utilizzerai per importare la chiave. Salva questo file come wrapped_key.bin.

Il seguente esempio di codice Go mostra il wrapping del materiale della chiave utilizzando la libreria 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))
}

Salva la stringa base64 di output o decodificala in un file binario: bash echo "BASE64_WRAPPED_KEY" | base64 --decode > wrapped_key.bin

Importa la chiave con wrapping

Importa la chiave con wrapping preparata come nuova versione della chiave di destinazione.

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

Controlla lo stato della versione della chiave importata

Lo stato iniziale di una versione della chiave importata è PENDING_IMPORT. Quando lo stato è ENABLED, la versione della chiave è stata importata correttamente. Se l'importazione non riesce, lo stato è IMPORT_FAILED.

Puoi controllare lo stato di una richiesta di importazione utilizzando Google Cloud CLI, la consoleCloud de Confiance o l'API Cloud Key Management Service.

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

Dopo l'importazione della versione iniziale della chiave, lo stato della chiave cambia in ENABLED. Per le chiavi simmetriche, devi impostare la versione della chiave importata come versione principale prima di poter utilizzare la chiave.

Reimporta una chiave eliminata in precedenza

Se devi ripristinare una versione della chiave importata in precedenza che si trova nello stato DESTROYED o IMPORT_FAILED allo stato ENABLED, puoi reimportare esattamente lo stesso materiale della chiave.

Il reimportazione di una versione della chiave eliminata utilizza la stessa procedura dell'importazione iniziale, utilizzando il job di importazione originale o un nuovo job di importazione (con lo stesso livello di protezione SOFTWARE).