Importer une version de clé dans Cloud KMS

Cette rubrique explique comment importer une clé cryptographique dans Cloud HSM ou Cloud Key Management Service en tant que nouvelle version de clé.

Pour en savoir plus sur l'importation de clés, y compris les limites et les restrictions, consultez la section Importation de clés.

Vous pouvez suivre la procédure décrite dans cette rubrique en 5 à 10 minutes, sans compter les étapes Avant de commencer. L'encapsulation manuelle de la clé ajoute de la complexité à la tâche.

Avant de commencer

Nous vous recommandons de créer un projet pour tester cette fonctionnalité, afin de faciliter le nettoyage après les tests et de vous assurer que vous disposez des autorisations Identity and Access Management (IAM) appropriées pour importer une clé.

Avant de pouvoir importer une clé, vous devez préparer le projet, le système local et la clé elle-même.

Préparer le projet

  1. Connectez-vous à votre compte Google Cloud. Si vous débutez sur Google Cloud, créez un compte pour évaluer les performances de nos produits en conditions réelles. Les nouveaux clients bénéficient également de 300 $ de crédits gratuits pour exécuter, tester et déployer des charges de travail.

  2. Dans Google Cloud Console, sur la page de sélection du projet, sélectionnez ou créez un projet Google Cloud.

    Accéder au sélecteur de projet

  3. Vérifiez que la facturation est activée pour votre projet Google Cloud.

  4. Activez l'API requise.

    Activer l'API

  5. Installez Google Cloud CLI.

  6. Pour initialiser gcloudCLI, exécutez la commande suivante : 

    gcloud init
    7.

  7. Dans Google Cloud Console, sur la page de sélection du projet, sélectionnez ou créez un projet Google Cloud.

    Accéder au sélecteur de projet

  8. Vérifiez que la facturation est activée pour votre projet Google Cloud.

  9. Activez l'API requise.

    Activer l'API

  10. Installez Google Cloud CLI.

  11. Pour initialiser gcloudCLI, exécutez la commande suivante : 

    gcloud init
    12.

  12. L'utilisateur effectuant l'importation doit disposer des autorisations IAM suivantes pour créer des trousseaux de clés, des clés et des tâches d'importation. Si l'utilisateur n'est pas le propriétaire du projet, vous pouvez lui attribuer les deux rôles prédéfinis suivants:

    • roles/editor
    • roles/cloudkms.importer

    Pour en savoir plus sur les rôles et les autorisations IAM disponibles pour Cloud KMS, consultez la page Autorisations et rôles.

Préparer le système local

Préparez le système local en choisissant l'une des options suivantes. L'encapsulation automatique des clés est recommandée pour la plupart des utilisateurs.

Préparer la clé

Vérifiez que l'algorithme et la longueur de votre clé sont compatibles. Les algorithmes autorisés pour une clé varient selon si la clé est utilisée pour le chiffrement symétrique, le chiffrement asymétrique ou la signature asymétrique, ainsi que si la clé est stockée dans un logiciel ou un HSM. Vous spécifiez l'algorithme de la clé dans le cadre de la requête d'importation.

Séparément, vous devez également vérifier la manière dont la clé est encodée et effectuer des ajustements si nécessaire.

Une fois que la version de clé a été créée ou importée, vous ne pouvez plus modifier les éléments suivants:

  • Le niveau de protection indique si la clé persiste dans un logiciel, dans un HSM ou dans un système de gestion de clés externe. Le matériel de la clé ne peut pas être déplacé d'un de ces environnements de stockage à un autre. Toutes les versions d'une clé disposent du même niveau de protection.

  • L'objectif indique si les versions de la clé sont utilisées pour le chiffrement symétrique, le chiffrement asymétrique ou la signature asymétrique. L'objectif de la clé limite les algorithmes pouvant être utilisés pour créer des versions de cette clé. Toutes les versions d'une clé ont le même objectif.

Si vous n'avez pas de clé à importer, mais que vous souhaitez valider la procédure d'importation, vous pouvez créer une clé symétrique sur le système local à l'aide de la commande suivante :

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

Utilisez cette clé uniquement pour les tests. Une clé créée de cette manière peut ne pas être appropriée pour une utilisation en production.

Si vous devez encapsuler la clé manuellement, faites-le avant de continuer avec les procédures de cette rubrique.

Créer la clé de ciblage et le trousseau de clés

Une clé Cloud KMS est un objet de conteneur qui contient zéro, une ou plusieurs versions de clé. Chaque version de clé contient une clé de chiffrement.

Lorsque vous importez une clé dans Cloud KMS ou Cloud HSM, la clé importée devient une nouvelle version de clé sur une clé Cloud KMS ou Cloud HSM existante. Dans le reste de cet article, cette clé est appelée clé cible. La clé cible doit exister avant de pouvoir y importer du matériel de clé.

L'importation d'une version de clé n'a aucun effet sur les versions existantes de cette clé. Toutefois, il est recommandé de créer une clé vide lors du test de l'importation de clé. Une clé vide n'a pas de version, n'est pas active et ne peut pas être utilisée.

Vous pouvez éventuellement spécifier que votre clé nouvellement créée ne peut contenir que des versions importées, ce qui empêche la génération accidentelle de nouvelles versions dans Cloud KMS.

Une clé existe sur un trousseau de clés. Dans cet article, ce trousseau de clés est appelé trousseau de clés cible. L'emplacement du trousseau de clés cible détermine l'emplacement où le matériel de clé est disponible après l'importation. Les clés Cloud HSM ne peuvent pas être créées ou importées dans certains emplacements. Une fois la clé créée, elle ne peut pas être transférée vers un autre trousseau ou à un autre emplacement.

Suivez ces étapes pour créer une clé vide sur un nouveau trousseau de clés à l'aide de la Google Cloud CLI ou de la console Google Cloud.

Console

  1. Dans la console Google Cloud, accédez à la page Gestion des clés.

    Accéder à Key Management

  2. Cliquez sur Créer un trousseau.

  3. Dans le champ Key ring name (Nom du trousseau), saisissez le nom du trousseau de clés.

  4. Sous Type d'emplacement, sélectionnez un type et un emplacement.

  5. Cliquez sur Créer. La page Créer une clé s'ouvre.

  6. Dans le champ Key name (Nom de la clé), saisissez le nom de votre clé.

  7. Pour Protection level (Niveau de protection), sélectionnez Software (Logiciel) ou HSM, puis cliquez sur Continue (Continuer).

  8. Pour Key material (Matériel de la clé), sélectionnez Imported key (Clé importée), puis cliquez sur Continue (Continuer). Cela empêche la création d'une version de clé initiale.

  9. Définissez le objectif et l'algorithme de la clé, puis cliquez sur Continuer.

  10. Facultatif: Si vous souhaitez que cette clé ne contienne que les versions de clé importées, sélectionnez Restreindre les versions de clé à importer uniquement. Cela vous évite de créer accidentellement des versions de clé dans Cloud KMS.

  11. Facultatif: Pour les clés importées, la rotation automatique est désactivée par défaut. Pour activer la rotation automatique, sélectionnez une valeur dans le champ Période de rotation des clés.

    Si vous activez la rotation automatique, les nouvelles versions de clé seront générées dans Cloud KMS et la version de clé importée ne sera plus la version de clé par défaut après une rotation.

  12. Cliquez sur Créer.

gcloud

Pour utiliser Cloud KMS sur la ligne de commande, commencez par installer la Google Cloud CLI ou passer à la dernière version en date.

  1. Créez le trousseau de clés de ciblage. Si vous avez l'intention d'importer dans une clé Cloud HSM, sélectionnez un emplacement compatible avec Cloud HSM.

    gcloud kms keyrings create KEY_RING \
  --location LOCATION

    Vous pouvez en savoir plus sur la création de trousseaux de clés.

  2. Créez la clé de ciblage.

    • Spécifiez l'objectif de la clé.
    • Empêchez la création d'une version initiale à l'aide de l'option --skip-initial-version-creation.
    • Facultatif: empêchez la création de versions dans Cloud KMS à l'aide de l'option --import-only.
    • Facultatif: ne spécifiez pas de règle de rotation. Si vous activez la rotation automatique, les nouvelles versions de clé seront générées dans Cloud KMS et la version de clé importée ne sera plus la version de clé par défaut après une rotation. Vous ne pouvez pas spécifier de règle de rotation si vous avez spécifié l'option --import-only.
    gcloud kms keys create KEY_NAME \
  --location LOCATION \
  --keyring KEY_RING \
  --purpose PURPOSE \
  --skip-initial-version-creation \
  --import-only

    En savoir plus sur la création de clés Cloud KMS ou de clés Cloud HSM.

Go

Pour exécuter ce code, commencez par configurer un environnement de développement Go, puis installez le SDK Cloud KMS pour Go.

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

Pour exécuter ce code, commencez par configurer un environnement de développement Java et installez le SDK Cloud KMS pour Java.

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

Pour exécuter ce code, commencez par configurer un environnement de développement Node.js, puis installez le SDK Cloud KMS pour Node.js.

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

Pour exécuter ce code, commencez par configurer un environnement de développement Python, puis installez le SDK Cloud KMS pour Python.

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,
        }
    )
    print(f"Created hsm key: {created_key.name}")

API

Ces exemples utilisent curl comme client HTTP pour démontrer l'utilisation de l'API. Pour en savoir plus sur le contrôle des accès, consultez la page Accéder à l'API Cloud KMS.

  1. Créez un trousseau de clés :

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

    Pour plus d'informations, consultez la documentation de l'API KeyRing.create.

  2. Créez une clé vide exclusivement dédiée à l'importation:

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

    Pour plus d'informations, consultez la documentation de l'API CryptoKey.create.

Le trousseau de clés et la clé existent désormais, mais la clé ne contient aucun matériel de clé, n'a aucune version et n'est pas active. Ensuite, vous créez une tâche d'importation.

Créer la tâche d'importation

Une tâche d'importation définit les caractéristiques des clés qu'elle importe, y compris les propriétés qui ne peuvent pas être modifiées après l'importation de la clé.

Le niveau de protection définit si les clés importées par cette tâche d'importation seront stockées dans un logiciel, dans un module de sécurité matérielle (HSM) ou dans un système de gestion de clés externe. Le niveau de protection ne peut plus être modifié une fois la clé importée.

La méthode d'importation définit l'algorithme utilisé pour créer la clé d'encapsulation qui protège les clés importées lors du transit de votre système local vers le projet Google Cloud cible. Vous pouvez choisir une clé RSA de 3 072 bits ou de 4 096 bits. Nous vous recommandons d'utiliser la clé d'encapsulation 3 072 bits, sauf si vous avez des exigences spécifiques.

Vous pouvez créer un job d'importation à l'aide de la gcloud CLI, de la console Google Cloud ou de l'API Cloud Key Management Service.

Console

  1. Accédez à la page Gestion des clés dans la console Google Cloud.

    Accéder à la page "Gestion des clés"

  2. Cliquez sur le nom du trousseau de clés de ciblage.

  3. Définissez le niveau de protection sur Logiciel ou HSM. Utilisez le même niveau de protection que celui défini pour la clé de ciblage.

  4. Cliquez sur Créer une tâche d'importation.

  5. Dans le champ Nom, saisissez le nom de la tâche d'importation.

  6. Dans le menu déroulant Méthode d'importation, définissez la méthode d'importation RSA 3 072 bits ou RSA 4 096 bits.

  7. Cliquez sur Créer.

gcloud

Pour utiliser Cloud KMS sur la ligne de commande, commencez par installer la Google Cloud CLI ou passer à la dernière version en date.

Utilisez une commande comme celle-ci pour créer une tâche d'importation.

gcloud kms import-jobs create IMPORT_JOB \
  --location LOCATION \
  --keyring KEY_RING \
  --import-method IMPORT_METHOD \
  --protection-level PROTECTION_LEVEL
  • Utilisez le même trousseau de clés et le même emplacement que la clé de ciblage.
  • Définissez le niveau de protection sur software ou hsm.
  • Définissez la méthode d'importation sur 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 ou rsa-oaep-4096-sha256.

Go

Pour exécuter ce code, commencez par configurer un environnement de développement Go, puis installez le SDK Cloud KMS pour Go.

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

Pour exécuter ce code, commencez par configurer un environnement de développement Java et installez le SDK Cloud KMS pour Java.

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

Pour exécuter ce code, commencez par configurer un environnement de développement Node.js, puis installez le SDK Cloud KMS pour Node.js.

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

Pour exécuter ce code, commencez par configurer un environnement de développement Python, puis installez le SDK Cloud KMS pour Python.

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

Ces exemples utilisent curl comme client HTTP pour démontrer l'utilisation de l'API. Pour en savoir plus sur le contrôle des accès, consultez la page Accéder à l'API Cloud KMS.

Pour créer une tâche d'importation, utilisez la méthode 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"}'

Remplacez les éléments suivants :

Vérifier l'état de la tâche d'importation

L'état initial d'une tâche d'importation est PENDING_GENERATION. Lorsque l'état est ACTIVE, vous pouvez l'utiliser pour importer des clés.

Une tâche d'importation expire au bout de trois jours. Si la tâche d'importation est arrivée à expiration, vous devez en créer une.

Vous pouvez vérifier l'état d'un job d'importation à l'aide de la Google Cloud CLI, de la console Google Cloud ou de l'API Cloud Key Management Service.

Console

  1. Accédez à la page Gestion des clés dans la console Google Cloud.

    Accéder à la page "Gestion des clés"

  2. Cliquez sur le nom du trousseau de clés contenant la tâche d'importation.

  3. Cliquez sur l'onglet Tâches d'importation situé en haut de la page.

  4. L'état est alors visible sous État, à côté du nom de la tâche d'importation.

gcloud

Pour utiliser Cloud KMS sur la ligne de commande, commencez par installer la Google Cloud CLI ou passer à la dernière version en date.

Lorsqu'une tâche d'importation est active, vous pouvez l'utiliser pour importer des clés. Cette opération peut prendre quelques minutes. Utilisez cette commande pour vérifier que la tâche d'importation est active. Utilisez l'emplacement et le trousseau de clés où vous avez créé la tâche d'importation.

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

Le résultat ressemble à ce qui suit :

state: ACTIVE

Go

Pour exécuter ce code, commencez par configurer un environnement de développement Go, puis installez le SDK Cloud KMS pour Go.

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

Pour exécuter ce code, commencez par configurer un environnement de développement Java et installez le SDK Cloud KMS pour Java.

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

Pour exécuter ce code, commencez par configurer un environnement de développement Node.js, puis installez le SDK Cloud KMS pour Node.js.

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

Pour exécuter ce code, commencez par configurer un environnement de développement Python, puis installez le SDK Cloud KMS pour Python.

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

Ces exemples utilisent curl comme client HTTP pour démontrer l'utilisation de l'API. Pour en savoir plus sur le contrôle des accès, consultez la page Accéder à l'API Cloud KMS.

Pour vérifier l'état d'une tâche d'importation, utilisez la méthode 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"

Dès que la tâche d'importation est active, vous pouvez effectuer une demande d'importation d'une clé.

Empêcher la modification des tâches d'importation

La tâche d'importation détermine de nombreuses caractéristiques de la clé importée, y compris l'algorithme de la clé et si une clé importée est une clé HSM ou une clé logicielle. Vous pouvez configurer des autorisations IAM pour empêcher les utilisateurs de créer des tâches d'importation, tout en leur permettant d'utiliser des tâches d'importation pour importer des clés.

  1. N'accordez l'autorisation importjobs.create qu'aux administrateurs de clé.
  2. Accordez l'autorisation importjobs.useToImport pour une tâche d'importation spécifique à l'opérateur qui utilisera cette tâche pour importer des clés.
  3. Lorsque vous créez la tâche d'importation, spécifiez le niveau de protection et l'algorithme pour les versions de clé importées à l'aide de celle-ci.

Jusqu'à l'expiration de la tâche d'importation, les utilisateurs disposant de importjobs.useToImport et n'ayant pas l'autorisation importjobs.create pour une tâche d'importation donnée peuvent importer des clés, mais ne peuvent pas modifier les caractéristiques de la tâche d'importation.

Importer la clé

Après avoir vérifié l'état de la tâche d'importation, vous pouvez envoyer une requête d'importation.

Vous utilisez différents indicateurs pour effectuer la requête d'importation, selon que vous souhaitez que Google Cloud CLI encapsule votre clé automatiquement ou que vous l'avez déjà encapsulée manuellement.

Quelle que soit l'encapsulation manuelle ou automatique de votre clé, vous devez définir l'algorithme sur un algorithme compatible qui correspond à la longueur de la clé réelle à importer et qui spécifie l'objectif de la clé).

  • Les clés ayant pour objectif ENCRYPT_DECRYPT utilisent l'algorithme google-symmetric-encryption et ont une longueur de 32.

  • Les clés ayant pour objectif ASYMMETRIC_DECRYPT ou ASYMMETRIC_SIGN acceptent divers algorithmes et longueurs.

    L'objectif d'une clé ne peut pas être modifié après la création de la clé, mais les versions de clé ultérieures peuvent être créées avec des longueurs différentes de la version de clé initiale.

Encapsulation automatique et importation d'une clé

Si vous souhaitez utiliser l'encapsulation automatique, vous devez utiliser la Google Cloud CLI. Utilisez une commande semblable à celle-ci. Définissez --target-key-file sur l'emplacement de la clé désencapsulée à encapsuler et importer. Ne définissez pas --wrapped-key-file.

Vous pouvez éventuellement définir l'option --public-key-file à l'emplacement où la clé publique a déjà été téléchargée. Lorsque vous importez un grand nombre de clés, cela empêche le téléchargement de la clé publique lors de chaque importation. Par exemple, vous pouvez écrire un script qui a téléchargé la clé publique une fois, puis fourni son emplacement lors de l'importation de chaque clé.

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 clé est encapsulée par la clé d'encapsulation associée à la tâche d'importation, transmise à Google Cloud et importée en tant que nouvelle version de clé sur la clé cible.

Importer manuellement une clé encapsulée

Suivez les instructions de cette section pour importer une clé que vous avez manuellement encapsulée. Définissez --wrapped-key-file sur l'emplacement de la clé que vous avez encapsulée manuellement. Ne définissez pas --target-key-file.

Vous pouvez éventuellement définir l'option --public-key-file à l'emplacement où la clé publique a déjà été téléchargée. Lorsque vous importez un grand nombre de clés, cela empêche le téléchargement de la clé publique lors de chaque importation. Par exemple, vous pouvez écrire un script qui a téléchargé la clé publique une fois, puis fourni son emplacement lors de l'importation de chaque clé.

Console

  1. Ouvrez la page Gestion des clés dans la console Google Cloud.

  2. Cliquez sur le nom du trousseau de clés contenant la tâche d'importation. La clé de ciblage s'affiche, ainsi que toutes les autres clés du trousseau.

  3. Cliquez sur le nom de la clé de ciblage, puis sur Importer la version de clé.

  4. Sélectionnez votre tâche d'importation dans la liste déroulante Select import job (Sélectionner une tâche d'importation).

  5. Dans le sélecteur Upload the wrapped key (Importer la clé encapsulée), sélectionnez la clé que vous avez déjà encapsulée.

  6. Si vous importez une clé asymétrique, sélectionnez l'algorithme dans la liste déroulante Algorithm (Algorithme). Une page Importer une version de clé semblable à celle-ci doit s'afficher :

    Importer une version de clé

  7. Cliquez sur Importer.

gcloud

Pour utiliser Cloud KMS sur la ligne de commande, commencez par installer la Google Cloud CLI ou passer à la dernière version en date.

Utilisez une commande semblable à celle-ci.

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

Pour plus d'informations, consultez la sortie de la commande gcloud kms keys versions import --help.

Go

Pour exécuter ce code, commencez par configurer un environnement de développement Go, puis installez le SDK Cloud KMS pour Go.

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

Pour exécuter ce code, commencez par configurer un environnement de développement Java et installez le SDK Cloud KMS pour Java.

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

Pour exécuter ce code, commencez par configurer un environnement de développement Node.js, puis installez le SDK Cloud KMS pour Node.js.

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

Pour exécuter ce code, commencez par configurer un environnement de développement Python, puis installez le SDK Cloud KMS pour Python.

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

Ces exemples utilisent curl comme client HTTP pour démontrer l'utilisation de l'API. Pour en savoir plus sur le contrôle des accès, consultez la page Accéder à l'API Cloud KMS.

Utilisez la méthode cryptoKeyVersions.import pour importer une clé.

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

Remplacez les éléments suivants :

  • IMPORT_JOB_ID: nom complet de la ressource de la tâche d'importation correspondante.

  • ALGORITHM: algorithm de la clé importée, qui est de type CryptoKeyVersionAlgorithm.

  • WRAPPED_KEY: clé encapsulée manuellement au format base64.

La requête d'importation de clé est lancée. Vous pouvez surveiller son état.

Vérifier l'état de la version de clé importée

L'état initial d'une version de clé importée est PENDING_IMPORT. Lorsque l'état indique ENABLED, la version de clé a bien été importée. Si l'importation échoue, l'état est IMPORT_FAILED.

Vous pouvez vérifier l'état d'une requête d'importation à l'aide de la Google Cloud CLI, de la console Google Cloud ou de l'API Cloud Key Management Service.

Console

  1. Ouvrez la page Gestion des clés dans la console Google Cloud.

  2. Cliquez sur le nom du trousseau de clés contenant la tâche d'importation.

  3. Cliquez sur l'onglet Tâches d'importation situé en haut de la page.

  4. L'état est alors visible sous État, à côté du nom de la tâche d'importation.

gcloud

Pour utiliser Cloud KMS sur la ligne de commande, commencez par installer la Google Cloud CLI ou passer à la dernière version en date.

Utilisez la commande versions list pour vérifier l'état. Utilisez les mêmes emplacements, trousseaux de clés de ciblage et clés de ciblage créés précédemment dans cette section.

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

Go

Pour exécuter ce code, commencez par configurer un environnement de développement Go, puis installez le SDK Cloud KMS pour Go.

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

Pour exécuter ce code, commencez par configurer un environnement de développement Java et installez le SDK Cloud KMS pour Java.

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

Pour exécuter ce code, commencez par configurer un environnement de développement Node.js, puis installez le SDK Cloud KMS pour Node.js.

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

Pour exécuter ce code, commencez par configurer un environnement de développement Python, puis installez le SDK Cloud KMS pour Python.

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

Ces exemples utilisent curl comme client HTTP pour démontrer l'utilisation de l'API. Pour en savoir plus sur le contrôle des accès, consultez la page Accéder à l'API Cloud KMS.

Appelez la méthode ImportJob.get et vérifiez la valeur du champ state. Si l'état (state) est défini sur PENDING_GENERATION, c'est que la tâche d'importation est toujours en cours de création. Revérifiez régulièrement l'état jusqu'à ce qu'il bascule sur ACTIVE.

Une fois la version initiale de la clé importée, l'état de la clé passe à Active (Actif). Pour les clés symétriques, vous devez définir la version de clé importée comme version principale avant de pouvoir utiliser la clé.

Clés symétriques : définir la version principale

Cette étape est requise lors de l'importation de clés symétriques et n'est pas pertinente pour les clés asymétriques. Une clé asymétrique ne possède pas de version principale. Vous devez utiliser la Google Cloud CLI pour définir la version principale.

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

Réimporter une clé précédemment détruite

Cloud Key Management Service permet la réimportation de clé, ce qui vous permet de restaurer une version de clé importée précédemment dans l'état DESTROYED ou IMPORT_FAILED à l'état ENABLED en fournissant le matériel d'origine de la clé. Si aucun matériel de clé d'origine n'a jamais été importé en raison de l'échec de l'importation initiale, n'importe quel matériel de clé peut être fourni.

Restrictions

  • Seules les versions CryptoKeyVersions précédemment importées peuvent être réimportées.
  • Le matériel de clé réimporté doit correspondre exactement au matériel de clé d'origine si la version a déjà été importée.
  • Les CryptoKeyVersions détruites avant le lancement de cette fonctionnalité ne peuvent pas être réimportées. Le champ reimport_eligible de CryptoKeyVersion indique true si la version peut être réimportée, et false dans le cas contraire.

Les clés logicielles et Cloud HSM peuvent être réimportées, mais pas les clés externes.

Réimporter une clé détruite

Créez un ImportJob pour la réimportation en suivant les étapes décrites dans la section Créer la tâche d'importation. Vous pouvez utiliser un ImportJob existant ou un nouvel ImportJob tant que le niveau de protection correspond au niveau de protection d'origine.

Console

  1. Accédez à la page Gestion des clés dans la console Google Cloud.

    Accéder à la page "Gestion des clés"

  2. Cliquez sur le nom du trousseau de clés contenant la clé dont vous souhaitez réimporter la version.

  3. Cliquez sur la clé dont vous souhaitez réimporter la version.

  4. Cliquez sur les trois points à côté de la version de clé que vous souhaitez réimporter.

  5. Sélectionnez Réimporter la version de clé

  6. Sélectionnez votre tâche d'importation dans la liste déroulante Select import job (Sélectionner une tâche d'importation).

  7. Dans le sélecteur Upload the wrapped key (Importer la clé encapsulée), sélectionnez la clé que vous avez déjà encapsulée. Cette clé doit correspondre au matériel de clé d'origine.

  8. Cliquez sur Reimporter.

gcloud

Pour utiliser Cloud KMS sur la ligne de commande, commencez par installer la Google Cloud CLI ou passer à la dernière version en date.

  1. Réimportez la version de clé à l'aide du matériel de clé d'origine.

    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

Ces exemples utilisent curl comme client HTTP pour démontrer l'utilisation de l'API. Pour en savoir plus sur le contrôle des accès, consultez la page Accéder à l'API Cloud KMS.

  1. Dans le corps de la requête de la méthode cryptoKeyVersions.import, définissez le champ cryptoKeyVersion sur le nom de version de clé de la version importée. Il doit s'agir d'un enfant de la clé cryptographique.

  2. Dans le corps de la requête, définissez le champ algorithm sur l'algorithme de la clé importée. Cette valeur doit correspondre à l'algorithme de la version de clé d'origine. Le champ algorithm est de type CryptoKeyVersionAlgorithm.

  3. Dans le corps de la requête, définissez le champ wrappedKeyMaterial sur le matériel de clé que vous avez déjà encapsulé.

  4. Appelez la méthode cryptoKeyVersions.import. La réponse de cryptoKeyVersions.import est du type CryptoKeyVersion. Lorsqu'une clé a bien été importée, son état est ENABLED et vous pouvez l'utiliser dans Cloud KMS.

Étapes suivantes

Précédent
Configurer l'encapsulation automatique des clés
Suivant
Valider une version de clé importée