Importa una versione della chiave in Cloud KMS

Questo argomento mostra come importare una chiave di crittografia in Cloud HSM o Cloud Key Management Service come nuova versione della chiave.

Per ulteriori dettagli sull'importazione delle chiavi, incluse limitazioni e vincoli, vedi Importazione delle chiavi.

Puoi completare i passaggi descritti in questo argomento in 5-10 minuti, esclusi i passaggi di Prima di iniziare. Il wrapping manuale della chiave aggiunge complessità all'attività.

Prima di iniziare

Ti consigliamo di creare un nuovo progetto per testare questa funzionalità, per semplificare la pulizia dopo il test e per assicurarti di disporre delle autorizzazioni IAM (Identity and Access Management) adeguate per importare una chiave.

Prima di poter importare una chiave, devi preparare il progetto, il sistema locale e la chiave stessa.

Preparazione del progetto

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Make sure that billing is enabled for your Google Cloud project.

4. Enable the required API.

   Enable the API

5. Install the Google Cloud CLI.

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

   gcloud init

7. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

8. Make sure that billing is enabled for your Google Cloud project.

9. Enable the required API.

   Enable the API

10. Install the Google Cloud CLI.

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

    gcloud init

12. L'utente che esegue l'importazione deve disporre delle seguenti autorizzazioni IAM per creare chiavi automatizzate, chiavi e job di importazione. Se l'utente non è il proprietario del progetto, puoi assegnare entrambi dei seguenti due ruoli predefiniti:

    • roles/editor
    • roles/cloudkms.importer

    Per ulteriori informazioni sui ruoli e sulle autorizzazioni IAM disponibili per Cloud KMS, consulta Autorizzazioni e ruoli.

Preparazione del sistema locale

Prepara il sistema locale scegliendo una delle seguenti opzioni. Il wrapping automatico delle chiavi è consigliato per la maggior parte degli utenti.

• Se vuoi consentire a Google Cloud CLI di eseguire automaticamente l'incapsulamento delle chiavi prima di trasmetterle a Google Cloud, devi installare la libreria di crittografia Pyca sul tuo sistema locale. La libreria Pyca viene utilizzata dal job di importazione che wrapping e protegge la chiave localmente prima di inviarla a Google Cloud.
• Se vuoi eseguire il wrapping delle chiavi manualmente, devi configurare OpenSSL per il wrapping manuale delle chiavi.

Preparazione della chiave

Verifica che l'algoritmo e la lunghezza della chiave siano supportati. Gli algoritmi consentiti per una chiave dipendono dal fatto che la chiave sia utilizzata per la crittografia simmetrica, la crittografia asimmetrica o la firma asimmetrica, nonché dal fatto che la chiave sia archiviata in un software o in un HSM. L'algoritmo della chiave viene specificato nell'ambito della richiesta di importazione.

Inoltre, devi anche verificare la modalità di codifica della chiave e apportare modifiche, se necessario.

I seguenti elementi non possono essere modificati per una versione della chiave dopo la sua creazione o importazione:

• Il livello di protezione indica se la chiave persiste nel software, in un HSM o in un sistema di gestione delle chiavi esterno. Il materiale delle chiavi non può essere trasferito da uno di questi ambienti di archiviazione a un altro. Tutte le versioni di una chiave hanno lo stesso livello di protezione.

• L'attributo purpose indica se le versioni della chiave vengono utilizzate per la crittografia simmetrica, la crittografia asimmetrica o la firma asimmetrica. Lo scopo della chiave limita i possibili algoritmi che possono essere utilizzati per creare versioni di quella chiave. Tutte le versioni di una chiave hanno lo stesso scopo.

Se non hai una chiave da importare, ma vuoi convalidare la procedura di importazione delle chiavi, puoi creare una chiave simmetrica sul sistema locale utilizzando il seguente comando:

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

Utilizza questa chiave solo per i test. Una chiave creata in questo modo potrebbe non essere appropriata per l'uso in produzione.

Se devi chiudere manualmente la chiave, effettua questa operazione prima di continuare con le procedure descritte in questo argomento.

Crea la chiave e il keyring di destinazione

Una chiave Cloud KMS è un oggetto contenitore che contiene zero o più versioni della chiave. Ogni versione della chiave contiene una chiave crittografica.

Quando importi una chiave in Cloud KMS o Cloud HSM, la chiave importata diventa una nuova versione della chiave in una chiave Cloud KMS o Cloud HSM esistente. Nel resto di questo argomento, questa chiave è chiamata chiave target. La chiave di destinazione deve esistere prima che tu possa importare il materiale della chiave.

L'importazione di una versione della chiave non influisce sulle versioni esistenti della chiave. Tuttavia, è consigliabile creare una chiave vuota durante il test dell'importazione delle chiavi. Una chiave vuota non ha una versione, non è attiva e non può essere utilizzata.

Facoltativamente, puoi specificare che la chiave appena creata può contenere solo versioni importate, il che impedisce la generazione accidentale di nuove versioni in Cloud KMS.

Una chiave esiste in un mazzo di chiavi; in questo argomento, questo mazzo di chiavi è chiamato mazzo di chiavi di destinazione. La posizione del keyring di destinazione determina la posizione dove il materiale della chiave è disponibile dopo l'importazione. Le chiavi Cloud HSM non possono essere create o importate in alcune località. Una volta creata, la chiave non può essere spostata in un altro portachiavi o in un'altra posizione.

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

Console

1. Nella console Google Cloud, vai alla pagina Gestione delle chiavi.

   Vai a Gestione delle chiavi

2. Fai clic su Crea keyring.

3. Nel campo Nome della chiave automatizzata, inserisci il nome della chiave automatizzata.

4. In Tipo di località, seleziona un tipo di località e una località.

5. Fai clic su Crea. Viene visualizzata la pagina Crea chiave.

6. Nel campo Nome chiave, inserisci il nome della chiave.

7. In Livello di protezione, seleziona Software o HSM e poi fai clic su Continua.

8. In Materiale della chiave, seleziona Chiave importata e poi fai clic su Continua. In questo modo viene impedita la creazione di una versione iniziale della chiave.

9. Imposta Scopi e Algoritmo per la chiave, poi fai clic su Continua.

10. (Facoltativo) Se vuoi che questa chiave contenga solo le versioni delle chiavi importate, seleziona Limita le versioni della chiave solo per importazione. In questo modo, eviterai di creare accidentalmente nuove versioni della chiave in Cloud KMS.

11. (Facoltativo) Per le chiavi importate, la rotazione automatica è disattivata per impostazione predefinita. Per attivare la rotazione automatica, seleziona un valore dal campo Periodo di rotazione della chiave.

    Se attivi la rotazione automatica, in Cloud KMS verranno generate nuove versioni della chiave e la versione della chiave importata non sarà più la versione predefinita dopo una rotazione.

12. Fai clic su Crea.

gcloud

Per utilizzare Cloud KMS sulla riga di comando, esegui l'installazione o l'upgrade alla versione più recente di Google Cloud CLI.

1. Crea il keyring di destinazione. Se intendi eseguire l'importazione in una chiave Cloud HSM, seleziona una località con il supporto di Cloud HSM.

   gcloud kms keyrings create KEY_RING \
     --location LOCATION
   

   Scopri di più sulla creazione di chiavi automatizzate.

2. Crea la chiave di destinazione.

   • Specifica lo scopo della chiave.
   • Impedisci la creazione di una versione iniziale utilizzando il flag --skip-initial-version-creation.
   • (Facoltativo) Impedisci la creazione di nuove versioni in Cloud KMS utilizzando il flag --import-only.
   • (Facoltativo) Non specificare un criterio di rotazione. Se attivi la rotazione automatica, in Cloud KMS verranno generate nuove versioni della chiave e la versione della chiave importata non sarà più la versione predefinita dopo una rotazione. Non puoi specificare un criterio di rotazione se hai specificato il flag --import-only.

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

   Scopri di più sulla creazione di chiavi Cloud KMS o chiavi Cloud HSM.

Go

Per eseguire questo codice, devi innanzitutto configurare un ambiente di sviluppo Go e installare l'SDK Go Cloud KMS.

import (
	"context"
	"fmt"
	"io"

	kms "cloud.google.com/go/kms/apiv1"
	"cloud.google.com/go/kms/apiv1/kmspb"
)

// createKeyForImport creates a new asymmetric signing key in Cloud HSM.
func createKeyForImport(w io.Writer, parent, id string) error {
	// parent := "projects/my-project/locations/us-east1/keyRings/my-key-ring"
	// id := "my-imported-key"

	// Create the client.
	ctx := context.Background()
	client, err := kms.NewKeyManagementClient(ctx)
	if err != nil {
		return fmt.Errorf("failed to create kms client: %w", err)
	}
	defer client.Close()

	// Build the request.
	req := &kmspb.CreateCryptoKeyRequest{
		Parent:      parent,
		CryptoKeyId: id,
		CryptoKey: &kmspb.CryptoKey{
			Purpose: kmspb.CryptoKey_ASYMMETRIC_SIGN,
			VersionTemplate: &kmspb.CryptoKeyVersionTemplate{
				ProtectionLevel: kmspb.ProtectionLevel_HSM,
				Algorithm:       kmspb.CryptoKeyVersion_EC_SIGN_P256_SHA256,
			},
			// Ensure that only imported versions may be added to this key.
			ImportOnly: true,
		},
		SkipInitialVersionCreation: true,
	}

	// Call the API.
	result, err := client.CreateCryptoKey(ctx, req)
	if err != nil {
		return fmt.Errorf("failed to create key: %w", err)
	}
	fmt.Fprintf(w, "Created key: %s\n", result.Name)
	return nil
}

Java

Per eseguire questo codice, devi innanzitutto configurare un ambiente di sviluppo Java e installare l'SDK Java Cloud KMS.

import com.google.cloud.kms.v1.CreateCryptoKeyRequest;
import com.google.cloud.kms.v1.CryptoKey;
import com.google.cloud.kms.v1.CryptoKey.CryptoKeyPurpose;
import com.google.cloud.kms.v1.CryptoKeyVersion.CryptoKeyVersionAlgorithm;
import com.google.cloud.kms.v1.CryptoKeyVersionTemplate;
import com.google.cloud.kms.v1.KeyManagementServiceClient;
import com.google.cloud.kms.v1.KeyRingName;
import com.google.cloud.kms.v1.ProtectionLevel;
import java.io.IOException;

public class CreateKeyForImport {

  public void createKeyForImport() throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";
    String locationId = "us-east1";
    String keyRingId = "my-key-ring";
    String id = "my-import-key";
    createKeyForImport(projectId, locationId, keyRingId, id);
  }

  // Create a new crypto key to hold imported key versions.
  public void createKeyForImport(String projectId, String locationId, String keyRingId, String id)
      throws IOException {
    // Initialize client that will be used to send requests. This client only
    // needs to be created once, and can be reused for multiple requests. After
    // completing all of your requests, call the "close" method on the client to
    // safely clean up any remaining background resources.
    try (KeyManagementServiceClient client = KeyManagementServiceClient.create()) {
      // Build the parent name from the project, location, and key ring.
      KeyRingName keyRingName = KeyRingName.of(projectId, locationId, keyRingId);

      // Create the crypto key.
      CryptoKey createdKey =
          client.createCryptoKey(
              CreateCryptoKeyRequest.newBuilder()
                  .setParent(keyRingName.toString())
                  .setCryptoKeyId(id)
                  .setCryptoKey(
                      CryptoKey.newBuilder()
                          .setPurpose(CryptoKeyPurpose.ASYMMETRIC_SIGN)
                          .setVersionTemplate(
                              CryptoKeyVersionTemplate.newBuilder()
                                  .setProtectionLevel(ProtectionLevel.HSM)
                                  .setAlgorithm(CryptoKeyVersionAlgorithm.EC_SIGN_P256_SHA256))
                          // Ensure that only imported versions may be
                          // added to this key.
                          .setImportOnly(true))
                  .setSkipInitialVersionCreation(true)
                  .build());

      System.out.printf("Created crypto key %s%n", createdKey.getName());
    }
  }
}

Node.js

Per eseguire questo codice, devi innanzitutto configurare un ambiente di sviluppo Node.js e installare l'SDK Node.js di Cloud KMS.

//
// TODO(developer): Uncomment these variables before running the sample.
//
// const projectId = 'my-project';
// const locationId = 'us-east1';
// const keyRingId = 'my-key-ring';
// const id = 'my-imported-key';

// Imports the Cloud KMS library
const {KeyManagementServiceClient} = require('@google-cloud/kms');

// Instantiates a client
const client = new KeyManagementServiceClient();

// Build the parent key ring name
const keyRingName = client.keyRingPath(projectId, locationId, keyRingId);

async function createKeyForImport() {
  const [key] = await client.createCryptoKey({
    parent: keyRingName,
    cryptoKeyId: id,
    cryptoKey: {
      purpose: 'ENCRYPT_DECRYPT',
      versionTemplate: {
        algorithm: 'GOOGLE_SYMMETRIC_ENCRYPTION',
        protectionLevel: 'HSM',
      },
      // Optional: ensure that only imported versions may be added to this
      // key.
      importOnly: true,
    },
    // Do not allow KMS to generate an initial version of this key.
    skipInitialVersionCreation: true,
  });

  console.log(`Created key for import: ${key.name}`);
  return key;
}

return createKeyForImport();

Python

Per eseguire questo codice, devi innanzitutto configurare un ambiente di sviluppo Python e installare l'SDK Python di Cloud KMS.

from google.cloud import kms


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

    Sets up an empty CryptoKey within a KeyRing for import.


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

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

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

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

    # Call the API.
    created_key = client.create_crypto_key(
        request={
            "parent": key_ring_name,
            "crypto_key_id": crypto_key_id,
            "crypto_key": key,
            # Do not allow KMS to generate an initial version of this key.
            "skip_initial_version_creation": True,
        }
    )
    print(f"Created hsm key: {created_key.name}")

API

Questi esempi utilizzano curl come client HTTP per dimostrare l'utilizzo dell'API. Per ulteriori informazioni sul controllo dell'accesso, consulta Accedere all'API Cloud KMS.

1. Crea un nuovo keyring:

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

   Per ulteriori informazioni, consulta la documentazione dell'API KeyRing.create.

2. Crea una chiave vuota di sola importazione:

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

   Per ulteriori informazioni, consulta la documentazione dell'API CryptoKey.create.

Il keyring e la chiave ora esistono, ma la chiave non contiene materiale della chiave, non ha una versione e non è attiva. Poi, crea un job di importazione.

Crea il job di importazione

Un job di importazione definisce le caratteristiche delle chiavi che importa, incluse le proprietà che non possono essere modificate dopo l'importazione della chiave.

Il livello di protezione definisce se le chiavi importate da questo job di importazione risiederanno in un software, in un HSM o in un sistema di gestione delle chiavi esterno. Il livello di protezione non può essere modificato dopo che la chiave è stata importata.

Il metodo di importazione definisce l'algoritmo utilizzato per creare la chiave di wrapping che protegge le chiavi importate durante il transito dal sistema locale al progetto Google Cloud di destinazione. Puoi scegliere una chiave RSA da 3072 o 4096 bit. A meno che tu non abbia requisiti specifici, è consigliata la chiave di wrapping di 3072 bit.

Nota: il metodo di importazione è diverso dall'algoritmo della chiave da importare. L'algoritmo della chiave viene specificato durante la richiesta di importazione.

Puoi creare un job di importazione utilizzando gcloud CLI, la console Google Cloud o l'API Cloud Key Management Service.

Console

1. Vai alla pagina Gestione delle chiavi nella console Google Cloud.

   Vai alla pagina Gestione chiavi

2. Fai clic sul nome del keyring di destinazione.

3. Imposta il livello di protezione su Software o HSM. Utilizza lo stesso livello di protezione impostato per la chiave di destinazione.

4. Fai clic su Crea job di importazione.

5. Nel campo Nome, inserisci il nome del job di importazione.

6. Nell'elenco a discesa Metodo di importazione, imposta il metodo di importazione su RSA 3072 bit o RSA 4096 bit.

7. Fai clic su Crea.

gcloud

Per utilizzare Cloud KMS sulla riga di comando, innanzitutto esegui l'installazione o l'upgrade alla versione più recente di Google Cloud CLI.

Utilizza un comando come il seguente per creare un job di importazione.

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

• Utilizza lo stesso mazzo di chiavi e la stessa posizione della chiave di destinazione.
• Imposta il livello di protezione su software o hsm.
• Imposta il metodo di importazione su rsa-oaep-3072-sha1-aes-256 rsa-oaep-4096-sha1-aes-256, rsa-oaep-3072-sha256-aes-256, rsa-oaep-4096-sha256-aes-256, rsa-oaep-3072-sha256 o rsa-oaep-4096-sha256.

Go

Per eseguire questo codice, devi innanzitutto configurare un ambiente di sviluppo Go e installare l'SDK Go Cloud KMS.

import (
	"context"
	"fmt"
	"io"

	kms "cloud.google.com/go/kms/apiv1"
	"cloud.google.com/go/kms/apiv1/kmspb"
)

// createImportJob creates a new job for importing keys into KMS.
func createImportJob(w io.Writer, parent, id string) error {
	// parent := "projects/PROJECT_ID/locations/global/keyRings/my-key-ring"
	// id := "my-import-job"

	// Create the client.
	ctx := context.Background()
	client, err := kms.NewKeyManagementClient(ctx)
	if err != nil {
		return fmt.Errorf("failed to create kms client: %w", err)
	}
	defer client.Close()

	// Build the request.
	req := &kmspb.CreateImportJobRequest{
		Parent:      parent,
		ImportJobId: id,
		ImportJob: &kmspb.ImportJob{
			// See allowed values and their descriptions at
			// https://cloud.google.com/kms/docs/algorithms#protection_levels
			ProtectionLevel: kmspb.ProtectionLevel_HSM,
			// See allowed values and their descriptions at
			// https://cloud.google.com/kms/docs/key-wrapping#import_methods
			ImportMethod: kmspb.ImportJob_RSA_OAEP_3072_SHA1_AES_256,
		},
	}

	// Call the API.
	result, err := client.CreateImportJob(ctx, req)
	if err != nil {
		return fmt.Errorf("failed to create import job: %w", err)
	}
	fmt.Fprintf(w, "Created import job: %s\n", result.Name)
	return nil
}

Java

Per eseguire questo codice, devi innanzitutto configurare un ambiente di sviluppo Java e installare l'SDK Java Cloud KMS.

import com.google.cloud.kms.v1.ImportJob;
import com.google.cloud.kms.v1.ImportJob.ImportMethod;
import com.google.cloud.kms.v1.KeyManagementServiceClient;
import com.google.cloud.kms.v1.KeyRingName;
import com.google.cloud.kms.v1.ProtectionLevel;
import java.io.IOException;

public class CreateImportJob {

  public void createImportJob() throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";
    String locationId = "us-east1";
    String keyRingId = "my-key-ring";
    String id = "my-import-job";
    createImportJob(projectId, locationId, keyRingId, id);
  }

  // Create a new import job.
  public void createImportJob(String projectId, String locationId, String keyRingId, String id)
      throws IOException {
    // Initialize client that will be used to send requests. This client only
    // needs to be created once, and can be reused for multiple requests. After
    // completing all of your requests, call the "close" method on the client to
    // safely clean up any remaining background resources.
    try (KeyManagementServiceClient client = KeyManagementServiceClient.create()) {
      // Build the parent name from the project, location, and key ring.
      KeyRingName keyRingName = KeyRingName.of(projectId, locationId, keyRingId);

      // Build the import job to create, with parameters.
      ImportJob importJob =
          ImportJob.newBuilder()
              // See allowed values and their descriptions at
              // https://cloud.google.com/kms/docs/algorithms#protection_levels
              .setProtectionLevel(ProtectionLevel.HSM)
              // See allowed values and their descriptions at
              // https://cloud.google.com/kms/docs/key-wrapping#import_methods
              .setImportMethod(ImportMethod.RSA_OAEP_3072_SHA1_AES_256)
              .build();

      // Create the import job.
      ImportJob createdImportJob = client.createImportJob(keyRingName, id, importJob);
      System.out.printf("Created import job %s%n", createdImportJob.getName());
    }
  }
}

Node.js

Per eseguire questo codice, devi innanzitutto configurare un ambiente di sviluppo Node.js e installare l'SDK Node.js di Cloud KMS.

//
// TODO(developer): Uncomment these variables before running the sample.
//
// const projectId = 'my-project';
// const locationId = 'us-east1';
// const keyRingId = 'my-key-ring';
// const id = 'my-import-job';

// Imports the Cloud KMS library
const {KeyManagementServiceClient} = require('@google-cloud/kms');

// Instantiates a client
const client = new KeyManagementServiceClient();

// Build the parent key ring name
const keyRingName = client.keyRingPath(projectId, locationId, keyRingId);

async function createImportJob() {
  const [importJob] = await client.createImportJob({
    parent: keyRingName,
    importJobId: id,
    importJob: {
      protectionLevel: 'HSM',
      importMethod: 'RSA_OAEP_3072_SHA256',
    },
  });

  console.log(`Created import job: ${importJob.name}`);
  return importJob;
}

return createImportJob();

Python

Per eseguire questo codice, devi innanzitutto configurare un ambiente di sviluppo Python e installare l'SDK Python Cloud KMS.

from google.cloud import kms


def create_import_job(
    project_id: str, location_id: str, key_ring_id: str, import_job_id: str
) -> None:
    """
    Create a new import job in Cloud KMS.

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

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

    # Retrieve the fully-qualified key_ring string.
    key_ring_name = client.key_ring_path(project_id, location_id, key_ring_id)

    # Set paramaters for the import job, allowed values for ImportMethod and ProtectionLevel found here:
    # https://googleapis.dev/python/cloudkms/latest/_modules/google/cloud/kms_v1/types/resources.html

    import_method = kms.ImportJob.ImportMethod.RSA_OAEP_3072_SHA1_AES_256
    protection_level = kms.ProtectionLevel.HSM
    import_job_params = {
        "import_method": import_method,
        "protection_level": protection_level,
    }

    # Call the client to create a new import job.
    import_job = client.create_import_job(
        {
            "parent": key_ring_name,
            "import_job_id": import_job_id,
            "import_job": import_job_params,
        }
    )

    print(f"Created import job: {import_job.name}")

API

Questi esempi utilizzano curl come client HTTP per dimostrare l'utilizzo dell'API. Per ulteriori informazioni sul controllo dell'accesso, consulta Accedere all'API Cloud KMS.

Per creare un job di importazione, utilizza il metodo ImportJobs.create:

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

Sostituisci quanto segue:

• IMPORT_METHOD: un metodo di wrapping delle chiavi supportato.
• PROTECTION_LEVEL: il livello di protezione delle versioni chiave importate da questo job di importazione.

Verifica dello 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 console Google Cloud o l'API Cloud Key Management Service.

Console

1. Vai alla pagina Gestione delle chiavi nella console Google Cloud.

   Vai alla pagina Gestione chiavi

2. Fai clic sul nome del keyring che contiene il job di importazione.

3. Fai clic sulla scheda Import Jobs (Importazioni) nella parte superiore della pagina.

4. Lo stato sarà visibile in Stato accanto al nome del compito di importazione.

gcloud

Per utilizzare Cloud KMS sulla riga di comando, innanzitutto installa o esegui l'upgrade alla versione più recente di Google Cloud CLI.

Quando un job di importazione è attivo, puoi utilizzarlo per importare le chiavi. L'operazione potrebbe richiedere qualche minuto. Utilizza questo comando per verificare che il job di importazione sia attivo. Utilizza la posizione e il portachiavi in cui hai creato il job di importazione.

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

L'output è simile al seguente:

state: ACTIVE

Go

Per eseguire questo codice, devi innanzitutto configurare un ambiente di sviluppo Go e installare l'SDK Go Cloud KMS.

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

Per eseguire questo codice, devi innanzitutto configurare un ambiente di sviluppo Java e installare l'SDK Java Cloud KMS.

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

Per eseguire questo codice, devi innanzitutto configurare un ambiente di sviluppo Node.js e installare l'SDK Node.js di Cloud KMS.

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

Per eseguire questo codice, devi innanzitutto configurare un ambiente di sviluppo Python e installare l'SDK Python di Cloud KMS.

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

Questi esempi utilizzano curl come client HTTP per dimostrare l'utilizzo dell'API. Per ulteriori informazioni sul controllo dell'accesso, consulta Accedere all'API Cloud KMS.

Per controllare lo stato di un job di importazione, utilizza il metodo 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"

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

Impedire la modifica dei job di importazione

Il job di importazione determina molte caratteristiche della chiave importata, tra cui l'algoritmo della chiave e se si tratta di una chiave HSM o di una chiave software. Puoi configurare le autorizzazioni IAM per impedire agli utenti di creare job di importazione, consentendo loro al contempo di utilizzare i job di importazione per importare le chiavi.

1. Concedi l'autorizzazione importjobs.create solo agli amministratori principali.
2. Concedi l'autorizzazione importjobs.useToImport per un job di importazione specifico all'operatore che lo utilizzerà per importare le chiavi.
3. Quando crei il job di importazione, specifica il livello di protezione e l'algoritmo per le versioni delle chiavi importate utilizzandolo.

Fino alla scadenza del job di importazione, gli utenti che dispongono dell'autorizzazione importjobs.useToImport e non dispongono dell'autorizzazione importjobs.create per un determinato job di importazione possono importare le chiavi, ma non possono modificare le caratteristiche del job di importazione.

Importa la chiave

Dopo aver verificato lo stato del job di importazione, puoi effettuare una richiesta di importazione.

Utilizza diversi flag per effettuare la richiesta di importazione, a seconda che tu voglia che Google Cloud CLI inserisca automaticamente la chiave o se hai già inserito la chiave manualmente.

Indipendentemente dal fatto che tu abbia eseguito l'wrapping della chiave manualmente o automaticamente, devi impostare l'algoritmo su un algoritmo supportato che corrisponda alla lunghezza della chiave effettiva da importare e specifica lo scopo della chiave.

• Le chiavi con scopo ENCRYPT_DECRYPT utilizzano l'algoritmo google-symmetric-encryption e hanno una lunghezza di 32.

• Le chiavi con scopo ASYMMETRIC_DECRYPT o ASYMMETRIC_SIGN supportano una serie di algoritmi e lunghezze.

  Lo scopo di una chiave non può essere modificato dopo la sua creazione, ma è possibile creare versioni successive della chiave con lunghezze diverse rispetto alla versione iniziale.

Importante: devi specificare l'algoritmo e la lunghezza effettivi della chiave che stai importando. Per ulteriori informazioni, consulta Preparazione della chiave.

Eseguire il wrapping e importare automaticamente una chiave

Se vuoi utilizzare il rientro automatico, devi utilizzare Google Cloud CLI. Utilizza un comando come il seguente. Imposta --target-key-file sulla posizione della chiave scomposta da avvolgere e importare. Non impostare --wrapped-key-file.

Facoltativamente, puoi impostare il flag --public-key-file sulla posizione in cui la chiave pubblica è già stata scaricata. Quando importi un numero elevato di chiavi, questo impedisce il download della chiave pubblica durante ogni importazione. Ad esempio, potresti scrivere uno script che scarichi la chiave pubblica una volta e poi ne fornisca la posizione durante l'importazione di ogni chiave.

gcloud kms keys versions import \
    --import-job IMPORT_JOB \
    --location LOCATION \
    --keyring KEY_RING \
    --key KEY_NAME \
    --algorithm ALGORITHM \
    --target-key-file PATH_TO_UNWRAPPED_KEY

La chiave viene sottoposta a wrapping dalla chiave di wrapping associata al job di importazione, trasmessa a Google Cloud e importata come nuova versione della chiave nella chiave di destinazione.

Importazione di una chiave con wrapping manuale

Segui le istruzioni riportate in questa sezione per importare una chiave che hai inserito manualmente. Imposta --wrapped-key-file sulla posizione della chiave che hai racchiuso manualmente. Non impostare --target-key-file.

Facoltativamente, puoi impostare il flag --public-key-file sulla posizione in cui la chiave pubblica è già stata scaricata. Quando importi un numero elevato di chiavi, questo impedisce il download della chiave pubblica durante ogni importazione. Ad esempio, potresti scrivere uno script che scarichi la chiave pubblica una volta, quindi fornisca la relativa posizione durante l'importazione di ogni chiave.

Console

1. Apri la pagina Gestione delle chiavi nella console Google Cloud.

2. Fai clic sul nome del keyring che contiene il job di importazione. Viene visualizzata la chiave di destinazione, insieme a tutte le altre chiavi del mazzo.

3. Fai clic sul nome della chiave di destinazione e poi su Importa versione della chiave.

4. Seleziona il job di importazione dal menu a discesa Seleziona job di importazione.

5. Nel selettore Carica la chiave con wrapping, seleziona la chiave che hai già con wrapping.

6. Se importi una chiave asimmetrica, seleziona l'algoritmo dal menu a discesa Algoritmo. La pagina Importa versione chiave dovrebbe avere un aspetto simile al seguente:

   

7. Fai clic su Importa.

gcloud

Per utilizzare Cloud KMS sulla riga di comando, esegui l'installazione o l'upgrade alla versione più recente di Google Cloud CLI.

Utilizza un comando come il seguente.

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

Per ulteriori informazioni, consulta l'output del comando gcloud kms keys versions import --help.

Go

Per eseguire questo codice, devi innanzitutto configurare un ambiente di sviluppo Go e installare l'SDK Go Cloud KMS.

import (
	"context"
	"crypto/ecdsa"
	"crypto/elliptic"
	"crypto/rand"
	"crypto/rsa"
	"crypto/sha1"
	"crypto/x509"
	"encoding/pem"
	"fmt"
	"io"

	kms "cloud.google.com/go/kms/apiv1"
	"cloud.google.com/go/kms/apiv1/kmspb"
	"github.com/google/tink/go/kwp/subtle"
)

// importManuallyWrappedKey wraps key material and imports it into KMS.
func importManuallyWrappedKey(w io.Writer, importJobName, cryptoKeyName string) error {
	// importJobName := "projects/PROJECT_ID/locations/global/keyRings/my-key-ring/importJobs/my-import-job"
	// cryptoKeyName := "projects/PROJECT_ID/locations/global/keyRings/my-key-ring/cryptoKeys/my-imported-key"

	// Generate a ECDSA keypair, and format the private key as PKCS #8 DER.
	key, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
	if err != nil {
		return fmt.Errorf("failed to generate keypair: %w", err)
	}
	keyBytes, err := x509.MarshalPKCS8PrivateKey(key)
	if err != nil {
		return fmt.Errorf("failed to format private key: %w", err)
	}

	// Create the client.
	ctx := context.Background()
	client, err := kms.NewKeyManagementClient(ctx)
	if err != nil {
		return fmt.Errorf("failed to create kms client: %w", err)
	}
	defer client.Close()

	// Generate a temporary 32-byte key for AES-KWP and wrap the key material.
	kwpKey := make([]byte, 32)
	if _, err := rand.Read(kwpKey); err != nil {
		return fmt.Errorf("failed to generate AES-KWP key: %w", err)
	}
	kwp, err := subtle.NewKWP(kwpKey)
	if err != nil {
		return fmt.Errorf("failed to create KWP cipher: %w", err)
	}
	wrappedTarget, err := kwp.Wrap(keyBytes)
	if err != nil {
		return fmt.Errorf("failed to wrap target key with KWP: %w", err)
	}

	// Retrieve the public key from the import job.
	importJob, err := client.GetImportJob(ctx, &kmspb.GetImportJobRequest{
		Name: importJobName,
	})
	if err != nil {
		return fmt.Errorf("failed to retrieve import job: %w", err)
	}
	pubBlock, _ := pem.Decode([]byte(importJob.PublicKey.Pem))
	pubAny, err := x509.ParsePKIXPublicKey(pubBlock.Bytes)
	if err != nil {
		return fmt.Errorf("failed to parse import job public key: %w", err)
	}
	pub, ok := pubAny.(*rsa.PublicKey)
	if !ok {
		return fmt.Errorf("unexpected public key type %T, want *rsa.PublicKey", pubAny)
	}

	// Wrap the KWP key using the import job key.
	wrappedWrappingKey, err := rsa.EncryptOAEP(sha1.New(), rand.Reader, pub, kwpKey, nil)
	if err != nil {
		return fmt.Errorf("failed to wrap KWP key: %w", err)
	}

	// Concatenate the wrapped KWP key and the wrapped target key.
	combined := append(wrappedWrappingKey, wrappedTarget...)

	// Build the request.
	req := &kmspb.ImportCryptoKeyVersionRequest{
		Parent:     cryptoKeyName,
		ImportJob:  importJobName,
		Algorithm:  kmspb.CryptoKeyVersion_EC_SIGN_P256_SHA256,
		WrappedKey: combined,
	}

	// Call the API.
	result, err := client.ImportCryptoKeyVersion(ctx, req)
	if err != nil {
		return fmt.Errorf("failed to import crypto key version: %w", err)
	}
	fmt.Fprintf(w, "Created crypto key version: %s\n", result.Name)
	return nil
}

Java

Per eseguire questo codice, devi innanzitutto configurare un ambiente di sviluppo Java e installare l'SDK Java Cloud KMS.

import com.google.cloud.kms.v1.CryptoKeyName;
import com.google.cloud.kms.v1.CryptoKeyVersion;
import com.google.cloud.kms.v1.ImportCryptoKeyVersionRequest;
import com.google.cloud.kms.v1.ImportJob;
import com.google.cloud.kms.v1.ImportJobName;
import com.google.cloud.kms.v1.KeyManagementServiceClient;
import com.google.crypto.tink.subtle.Kwp;
import com.google.protobuf.ByteString;
import java.io.IOException;
import java.security.GeneralSecurityException;
import java.security.KeyFactory;
import java.security.KeyPair;
import java.security.KeyPairGenerator;
import java.security.PublicKey;
import java.security.SecureRandom;
import java.security.spec.ECGenParameterSpec;
import java.security.spec.MGF1ParameterSpec;
import java.security.spec.X509EncodedKeySpec;
import java.util.Base64;
import javax.crypto.Cipher;
import javax.crypto.spec.OAEPParameterSpec;
import javax.crypto.spec.PSource;

public class ImportManuallyWrappedKey {

  public void importManuallyWrappedKey() throws GeneralSecurityException, IOException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";
    String locationId = "us-east1";
    String keyRingId = "my-key-ring";
    String cryptoKeyId = "my-crypto-key";
    String importJobId = "my-import-job";
    importManuallyWrappedKey(projectId, locationId, keyRingId, cryptoKeyId, importJobId);
  }

  // Generates and imports local key material into Cloud KMS.
  public void importManuallyWrappedKey(
      String projectId, String locationId, String keyRingId, String cryptoKeyId, String importJobId)
      throws GeneralSecurityException, IOException {

    // Generate a new ECDSA keypair, and format the private key as PKCS #8 DER.
    KeyPairGenerator generator = KeyPairGenerator.getInstance("EC");
    generator.initialize(new ECGenParameterSpec("secp256r1"));
    KeyPair kp = generator.generateKeyPair();
    byte[] privateBytes = kp.getPrivate().getEncoded();

    // Initialize client that will be used to send requests. This client only
    // needs to be created once, and can be reused for multiple requests. After
    // completing all of your requests, call the "close" method on the client to
    // safely clean up any remaining background resources.
    try (KeyManagementServiceClient client = KeyManagementServiceClient.create()) {
      // Build the crypto key and import job names from the project, location,
      // key ring, and ID.
      final CryptoKeyName cryptoKeyName =
          CryptoKeyName.of(projectId, locationId, keyRingId, cryptoKeyId);
      final ImportJobName importJobName =
          ImportJobName.of(projectId, locationId, keyRingId, importJobId);

      // Generate a temporary 32-byte key for AES-KWP and wrap the key material.
      byte[] kwpKey = new byte[32];
      new SecureRandom().nextBytes(kwpKey);
      Kwp kwp = new Kwp(kwpKey);
      final byte[] wrappedTargetKey = kwp.wrap(privateBytes);

      // Retrieve the public key from the import job.
      ImportJob importJob = client.getImportJob(importJobName);
      String publicKeyStr = importJob.getPublicKey().getPem();
      // Manually convert PEM to DER. :-(
      publicKeyStr = publicKeyStr.replace("-----BEGIN PUBLIC KEY-----", "");
      publicKeyStr = publicKeyStr.replace("-----END PUBLIC KEY-----", "");
      publicKeyStr = publicKeyStr.replaceAll("\n", "");
      byte[] publicKeyBytes = Base64.getDecoder().decode(publicKeyStr);
      PublicKey publicKey =
          KeyFactory.getInstance("RSA").generatePublic(new X509EncodedKeySpec(publicKeyBytes));

      // Wrap the KWP key using the import job key.
      Cipher cipher = Cipher.getInstance("RSA/ECB/OAEPWithSHA-1AndMGF1Padding");
      cipher.init(
          Cipher.ENCRYPT_MODE,
          publicKey,
          new OAEPParameterSpec(
              "SHA-1", "MGF1", MGF1ParameterSpec.SHA1, PSource.PSpecified.DEFAULT));
      byte[] wrappedWrappingKey = cipher.doFinal(kwpKey);

      // Concatenate the wrapped KWP key and the wrapped target key.
      ByteString combinedWrappedKeys =
          ByteString.copyFrom(wrappedWrappingKey).concat(ByteString.copyFrom(wrappedTargetKey));

      // Import the wrapped key material.
      CryptoKeyVersion version =
          client.importCryptoKeyVersion(
              ImportCryptoKeyVersionRequest.newBuilder()
                  .setParent(cryptoKeyName.toString())
                  .setImportJob(importJobName.toString())
                  .setAlgorithm(CryptoKeyVersion.CryptoKeyVersionAlgorithm.EC_SIGN_P256_SHA256)
                  .setRsaAesWrappedKey(combinedWrappedKeys)
                  .build());

      System.out.printf("Imported: %s%n", version.getName());
    }
  }
}

Node.js

Per eseguire questo codice, devi innanzitutto configurare un ambiente di sviluppo Node.js e installare l'SDK Node.js di Cloud KMS.

//
// TODO(developer): Uncomment these variables before running the sample.
//
// const projectId = 'my-project';
// const locationId = 'us-east1';
// const keyRingId = 'my-key-ring';
// const cryptoKeyId = 'my-imported-key';
// const importJobId = 'my-import-job';

// Imports the Cloud KMS library
const {KeyManagementServiceClient} = require('@google-cloud/kms');

// Instantiates a client
const client = new KeyManagementServiceClient();

// Build the crypto key and importjob resource names
const cryptoKeyName = client.cryptoKeyPath(
  projectId,
  locationId,
  keyRingId,
  cryptoKeyId
);
const importJobName = client.importJobPath(
  projectId,
  locationId,
  keyRingId,
  importJobId
);

async function wrapAndImportKey() {
  // Generate a 32-byte key to import.
  const crypto = require('crypto');
  const targetKey = crypto.randomBytes(32);

  const [importJob] = await client.getImportJob({name: importJobName});

  // Wrap the target key using the import job key
  const wrappedTargetKey = crypto.publicEncrypt(
    {
      key: importJob.publicKey.pem,
      oaepHash: 'sha256',
      padding: crypto.constants.RSA_PKCS1_OAEP_PADDING,
    },
    targetKey
  );

  // Import the target key version
  const [version] = await client.importCryptoKeyVersion({
    parent: cryptoKeyName,
    importJob: importJobName,
    algorithm: 'GOOGLE_SYMMETRIC_ENCRYPTION',
    wrappedKey: wrappedTargetKey,
  });

  console.log(`Imported key version: ${version.name}`);
  return version;
}

return wrapAndImportKey();

Python

Per eseguire questo codice, devi innanzitutto configurare un ambiente di sviluppo Python e installare l'SDK Python Cloud KMS.

import os

# Import the client library and Python standard cryptographic libraries.
from cryptography.hazmat import backends
from cryptography.hazmat.primitives import hashes
from cryptography.hazmat.primitives import keywrap
from cryptography.hazmat.primitives import serialization
from cryptography.hazmat.primitives.asymmetric import ec
from cryptography.hazmat.primitives.asymmetric import padding
from google.cloud import kms


def import_manually_wrapped_key(
    project_id: str,
    location_id: str,
    key_ring_id: str,
    crypto_key_id: str,
    import_job_id: str,
) -> None:
    """
    Generates and imports local key material to Cloud KMS.

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

    # Generate some key material in Python and format it in PKCS #8 DER as
    # required by Google Cloud KMS.
    key = ec.generate_private_key(ec.SECP256R1, backends.default_backend())
    formatted_key = key.private_bytes(
        serialization.Encoding.DER,
        serialization.PrivateFormat.PKCS8,
        serialization.NoEncryption(),
    )

    print(f"Generated key bytes: {formatted_key!r}")

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

    # Retrieve the fully-qualified crypto_key and import_job string.
    crypto_key_name = client.crypto_key_path(
        project_id, location_id, key_ring_id, crypto_key_id
    )
    import_job_name = client.import_job_path(
        project_id, location_id, key_ring_id, import_job_id
    )

    # Generate a temporary 32-byte key for AES-KWP and wrap the key material.
    kwp_key = os.urandom(32)
    wrapped_target_key = keywrap.aes_key_wrap_with_padding(
        kwp_key, formatted_key, backends.default_backend()
    )

    # Retrieve the public key from the import job.
    import_job = client.get_import_job(name=import_job_name)
    import_job_pub = serialization.load_pem_public_key(
        bytes(import_job.public_key.pem, "UTF-8"), backends.default_backend()
    )

    # Wrap the KWP key using the import job key.
    wrapped_kwp_key = import_job_pub.encrypt(
        kwp_key,
        padding.OAEP(
            mgf=padding.MGF1(algorithm=hashes.SHA1()),
            algorithm=hashes.SHA1(),
            label=None,
        ),
    )

    # Import the wrapped key material.
    client.import_crypto_key_version(
        {
            "parent": crypto_key_name,
            "import_job": import_job_name,
            "algorithm": kms.CryptoKeyVersion.CryptoKeyVersionAlgorithm.EC_SIGN_P256_SHA256,
            "rsa_aes_wrapped_key": wrapped_kwp_key + wrapped_target_key,
        }
    )

    print(f"Imported: {import_job.name}")

API

Questi esempi utilizzano curl come client HTTP per dimostrare l'utilizzo dell'API. Per ulteriori informazioni sul controllo dell'accesso, consulta Accedere all'API Cloud KMS.

Utilizza il metodo cryptoKeyVersions.import per importare una chiave.

curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME/cryptoKeyVersions:import" \
    --request "POST" \
    --header "authorization: Bearer TOKEN" \
    --header "content-type: application/json" \
    --data '{"importJob": "IMPORT_JOB_ID", "algorithm": "ALGORITHM", "wrappedKey": "WRAPPED_KEY"}'

Sostituisci quanto segue:

• IMPORT_JOB_ID: il nome completo della risorsa del job di importazione corrispondente.

• ALGORITHM: il algorithm della chiave in fase di importazione, che è di tipo CryptoKeyVersionAlgorithm.

• WRAPPED_KEY: la chiave con wrapping manuale in formato base64.

Viene avviata la richiesta di importazione delle chiavi. Puoi monitorarne lo stato.

Controllare 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 console Google Cloud o l'API Cloud Key Management Service.

Console

1. Apri la pagina Gestione delle chiavi nella console Google Cloud.

2. Fai clic sul nome del keyring che contiene il job di importazione.

3. Fai clic sulla scheda Import Jobs (Importazioni) nella parte superiore della pagina.

4. Lo stato sarà visibile in Stato accanto al nome del compito di importazione.

gcloud

Per utilizzare Cloud KMS sulla riga di comando, esegui l'installazione o l'upgrade alla versione più recente di Google Cloud CLI.

Utilizza il comando versions list per controllare lo stato. Utilizza la stessa posizione, la stessa chiave automatizzata di destinazione e la stessa chiave di destinazione che hai creato in precedenza in questo argomento.

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

Go

Per eseguire questo codice, devi innanzitutto configurare un ambiente di sviluppo Go e installare l'SDK Go Cloud KMS.

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

Per eseguire questo codice, devi innanzitutto configurare un ambiente di sviluppo Java e installare l'SDK Java Cloud KMS.

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

Per eseguire questo codice, devi innanzitutto configurare un ambiente di sviluppo Node.js e installare l'SDK Node.js di Cloud KMS.

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

Per eseguire questo codice, devi innanzitutto configurare un ambiente di sviluppo Python e installare l'SDK Python Cloud KMS.

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

Questi esempi utilizzano curl come client HTTP per dimostrare l'utilizzo dell'API. Per ulteriori informazioni sul controllo dell'accesso, consulta Accedere all'API Cloud KMS.

Chiama il metodo ImportJob.get e controlla il campo state. Se state è PENDING_GENERATION, il job di importazione è ancora in fase di creazione. Controlla periodicamente lo stato finché non diventa ACTIVE.

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

Chiavi simmetriche: imposta la versione principale

Questo passaggio è necessario per l'importazione delle chiavi simmetriche e non è pertinente per le chiavi asimmetriche. Una chiave asimmetrica non ha una versione principale. Devi utilizzare Google Cloud CLI per impostare la versione principale.

Suggerimento: in genere KEY_VERSION è 1, perché la versione importata è la prima versione della chiave.

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

Reimporta una chiave eliminata in precedenza

Cloud Key Management Service supporta la reimportazione della chiave, che consente di ripristinare una versione della chiave importata in precedenza in stato DESTROYED o IMPORT_FAILED allo stato ENABLED fornendo il materiale della chiave originale. Se non è stato mai importato materiale chiave originale a causa di un errore di importazione iniziale, è possibile fornire qualsiasi materiale chiave.

Limitazioni

• È possibile reimportare solo i CryptoKeyVersions importati in precedenza.
• Il materiale della chiave reimportato deve corrispondere esattamente a quello originale se la versione è stata precedentemente importata correttamente.
• CryptoKeyVersions distrutti prima del rilascio di questa funzionalità non possono essere importati di nuovo. Il campo reimport_eligible di CryptoKeyVersion è true se la versione è idonea per la reimportazione e false in caso contrario.

Le chiavi software e Cloud HSM possono essere reimportate, ma non le chiavi esterne.

Reimportazione di una chiave eliminata

Crea un ImportJob per la reimportazione seguendo i passaggi descritti in Creare il job di importazione. Puoi utilizzare un ImportJob esistente o uno nuovo, purché il livello di protezione corrisponda a quello originale.ImportJob

Console

1. Vai alla pagina Gestione delle chiavi nella console Google Cloud.

   Vai alla pagina Gestione chiavi

2. Fai clic sul nome del keyring contenente la chiave di cui reimporterai la versione.

3. Fai clic sulla chiave di cui vuoi importare di nuovo la versione.

4. Fai clic sui tre puntini accanto alla versione della chiave che vuoi importare di nuovo.

5. Seleziona Reimporta versione della chiave.

6. Seleziona il job di importazione dal menu a discesa Seleziona job di importazione.

7. Nel selettore Carica la chiave con wrapping, seleziona la chiave che hai già con wrapping. Questa chiave deve corrispondere al materiale della chiave originale.

8. Fai clic su Importa di nuovo.

gcloud

Per utilizzare Cloud KMS sulla riga di comando, esegui l'installazione o l'upgrade alla versione più recente di Google Cloud CLI.

1. Reimporta la versione della chiave utilizzando il materiale chiave originale.

   gcloud kms keys versions import \
   --location LOCATION \
   --keyring KEY_RING \
   --key KEY_NAME \
   --version KEY_VERSION \
   --algorithm ALGORITHM \
   --import-job IMPORT_JOB \
   --target-key-file PATH_TO_KEY \
   

API

Questi esempi utilizzano curl come client HTTP per dimostrare l'utilizzo dell'API. Per ulteriori informazioni sul controllo dell'accesso, consulta Accedere all'API Cloud KMS.

1. Nel corpo della richiesta del metodo cryptoKeyVersions.import, imposta il campo cryptoKeyVersion sul nome della versione della chiave della versione da importare. Deve essere una chiave secondaria della chiave di crittografia.

2. Nel corpo della richiesta, imposta il campo algorithm sull'algoritmo della chiave da importare. Questo valore deve corrispondere all'algoritmo della versione originale della chiave. Il campo algorithm è di tipo CryptoKeyVersionAlgorithm.

3. Nel corpo della richiesta, imposta il campo wrappedKeyMaterial sul materiale chiave che hai già incapsulato.

4. Chiama il metodo cryptoKeyVersions.import. La risposta cryptoKeyVersions.import è di tipo CryptoKeyVersion. Quando una chiave viene importata correttamente, il suo stato è ENABLED e puoi utilizzarla in Cloud KMS.

Passaggi successivi

• Verifica una chiave importata. Dopo aver confermato che il materiale della chiave importato è identico alla chiave originale, puoi utilizzare la chiave per la firma o per proteggere i dati.
• Risolvi i problemi relativi a un'importazione di chiavi non riuscita.