Importation de clés à sécurité quantique

Aperçu

Ce produit ou cette fonctionnalité sont soumis aux "Conditions des offres de pré-DG" de la section "Conditions générales du service" des Conditions spécifiques du service. Les produits et fonctionnalités pré-DG sont disponibles "en l'état" et peuvent avoir une compatibilité limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Ce guide vous explique comment importer une clé cryptographique dans Cloud Key Management Service en tant que nouvelle version de clé à l'aide d'une méthode d'importation à sécurité quantique. Cette approche permet de protéger la clé en transit contre les attaques de type "Récolter maintenant, déchiffrer plus tard" (HNDL) par les futurs ordinateurs quantiques.

L'importation de clés à sécurité quantique utilise des outils de cryptographie post-quantique (PQC) standards, y compris des mécanismes d'encapsulation de clés (KEM) et le chiffrement hybride à clé publique (HPKE) pour protéger votre clé en transit.

L'importation de clés à sécurité quantique est compatible avec les clés logicielles (niveau de protection SOFTWARE).

Avant de commencer

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

Préparer le projet

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 sans frais pour exécuter, tester et déployer des charges de travail.

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

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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

Verify that billing is enabled for your Google Cloud project.

Enable the required API.

Roles required to enable APIs

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

Enable the API

Installez la Google Cloud CLI.

Si vous utilisez un fournisseur d'identité (IdP) externe, vous devez d'abord vous connecter à la gcloud CLI avec votre identité fédérée.

Pour initialiser la gcloud CLI, exécutez la commande suivante :

gcloud init

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

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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

Verify that billing is enabled for your Google Cloud project.

Enable the required API.

Roles required to enable APIs

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

Enable the API

Installez la Google Cloud CLI.

Si vous utilisez un fournisseur d'identité (IdP) externe, vous devez d'abord vous connecter à la gcloud CLI avec votre identité fédérée.

Pour initialiser la gcloud CLI, exécutez la commande suivante :

gcloud init

Rôles requis

Pour obtenir les autorisations nécessaires pour importer une clé, demandez à votre administrateur de vous accorder les rôles IAM suivants sur le trousseau de clés :

• Pour importer uniquement dans des clés existantes : Importateur Cloud KMS (roles/cloudkms.importer)
• Pour importer des clés : Administrateur Cloud KMS (roles/cloudkms.admin)

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.

Préparer le système local

Vous avez besoin d'une bibliothèque cryptographique sur votre système local qui prend en charge les outils de cryptographie post-quantique (PQC), y compris les mécanismes d'encapsulation de clé (KEM) et le chiffrement à clé publique hybride (HPKE). Vous pouvez utiliser Tink, OpenSSL ou une autre bibliothèque de chiffrement compatible avec les éléments suivants :

• Chiffrement hybride à clé publique (HPKE)
• L'un des algorithmes KEM suivants :
  • ML-KEM-768
  • ML-KEM-1024
  • X-WING (un hybride de ML-KEM-768 et X25519)
• Fonction de dérivation de clé (KDF) HKDF-SHA256
• Chiffrement authentifié avec les données associées (AEAD) à l'aide de l'algorithme AES-256-GCM

Préparer la clé

Vérifiez que l'algorithme et la longueur de votre clé sont compatibles. Toutes les versions d'une clé doivent avoir le même niveau de protection (SOFTWARE).

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

Lorsque vous importez un matériel de clé, il devient une nouvelle version de clé sur une clé existante. Cette clé est appelée clé cible. Le trousseau de clés cible et la clé cible doivent exister avant que vous puissiez importer du matériel de clé.

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

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 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 Nom de la clé, saisissez le nom de votre clé.

7. Dans le champ Niveau de protection, sélectionnez Logiciel.

8. Dans le champ Matériel de clé, sélectionnez Clé importée, puis cliquez sur Continuer. Cela empêche la création d'une version de clé initiale.

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

10. Facultatif : Si vous souhaitez que cette clé ne contienne que des versions importées, sélectionnez Limiter les versions de clé à l'importation. Cela vous empêche 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 ou mettre à jour Google Cloud CLI.

1. Créez le trousseau de clés de ciblage. Choisissez un emplacement compatible avec le niveau de protection que vous souhaitez utiliser. Pour en savoir plus sur les emplacements compatibles, consultez Emplacements Cloud KMS.

   gcloud kms keyrings create KEY_RING \
     --location LOCATION
   

   Pour en savoir plus sur la création de trousseaux de clés, consultez cet article.

2. Créez la clé cible à l'aide de la commande kms keys create avec le flag --skip-initial-version-creation. Cela crée une clé sans version initiale afin que le matériel de clé importé soit la version 1. Utilisez l'option --import-only pour empêcher Cloud KMS de générer du matériel de clé pour les nouvelles versions de clé. Lorsque ce paramètre est défini, les nouvelles versions de clé pour cette clé doivent être importées. Les clés créées en tant que --import-only doivent être permutées manuellement.

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

   Remplacez les éléments suivants :

   • KEY_NAME : nom que vous souhaitez utiliser pour la clé.
   • LOCATION : emplacement du trousseau de clés.
   • KEY_RING : trousseau de clés dans lequel vous souhaitez créer la clé.
   • PURPOSE : objectif que vous souhaitez utiliser pour la clé.

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, réservée à l'importation :

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

   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 le niveau de protection et la méthode d'importation.

L'importation de clés à sécurité quantique n'est acceptée que pour le niveau de protection SOFTWARE. Choisissez l'une des méthodes d'importation à sécurité quantique suivantes :

• HPKE_KEM_XWING_HKDF_SHA256_AES_256_GCM
• HPKE_KEM_ML_KEM_768_HKDF_SHA256_AES_256_GCM

• HPKE_KEM_ML_KEM_1024_HKDF_SHA256_AES_256_GCM

gcloud

Exécutez la commande suivante pour créer une tâche d'importation avec une méthode d'importation à sécurité quantique :

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

Remplacez les éléments suivants :

• IMPORT_JOB : nom unique à utiliser pour le job d'importation.
• LOCATION : emplacement du trousseau de clés dans lequel vous avez créé votre clé cible.
• KEY_RING : nom du trousseau de clés dans lequel vous avez créé votre clé cible.
• IMPORT_METHOD : méthode d'importation à sécurité quantique que vous souhaitez utiliser (par exemple, hpke-kem-xwing-hkdf-sha256-aes-256-gcm).

REST

Appelez la méthode keyRings.importJobs.create :

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

Remplacez les éléments suivants :

• PROJECT_ID : identifiant de votre projet Cloud KMS.
• LOCATION : emplacement du trousseau de clés dans lequel vous avez créé votre clé cible.
• KEY_RING : nom du trousseau de clés dans lequel vous avez créé votre clé cible.
• IMPORT_JOB : nom unique à utiliser pour le job d'importation.
• TOKEN : jeton permettant d'authentifier la requête.
• IMPORT_METHOD : méthode d'importation à sécurité quantique que vous souhaitez utiliser (par exemple, HPKE_KEM_XWING_HKDF_SHA256_AES_256_GCM).

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'une tâche d'importation à l'aide de Google Cloud CLI, de la consoleGoogle 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 ou mettre à jour Google Cloud CLI.

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é.

Récupérer la clé publique d'encapsulation

Une fois la tâche d'importation ACTIVE, récupérez la clé publique qui y est associée. Vous utiliserez cette clé publique sur votre système local pour encapsuler le matériel de clé que vous souhaitez importer.

gcloud

Exécutez la commande suivante pour télécharger la clé publique :

gcloud kms import-jobs describe IMPORT_JOB 

    --location LOCATION 

    --keyring KEY_RING 

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

Remplacez les éléments suivants :

• IMPORT_JOB : nom du job d'importation.
• LOCATION : emplacement du trousseau de clés dans lequel vous avez créé le job d'importation.
• KEY_RING : nom du trousseau de clés dans lequel vous avez créé le job d'importation.

La clé publique est encodée en base64.

REST

1. Appelez la méthode keyRings.importJobs.get.
2. Récupérez la clé publique à partir du champ publicKey.data de la réponse et enregistrez-la localement sous le nom public_key.data.

Préparer et encapsuler votre matériel de clé

Utilisez une bibliothèque cryptographique externe compatible sur votre système local pour encapsuler le matériel de clé à l'aide de la clé d'encapsulation publique récupérée.

Le processus d'encapsulation doit effectuer HPKE.Seal() (RFC 9180) pour produire une clé encapsulée. Cette opération effectue les étapes suivantes :

1. Encapsulez la clé publique récupérée pour générer une clé secrète partagée et une clé d'encapsulation.
2. Dérivez une clé symétrique éphémère du secret partagé à l'aide de HKDF-SHA256.
3. Chiffrez votre matériel de clé avec la clé éphémère à l'aide d'AES-256-GCM.
4. Concaténez la clé d'encapsulation et le matériel de clé chiffré sous forme de texte chiffré. Il s'agit de la clé encapsulée résultante que vous utiliserez pour importer la clé. Enregistrez-le sous le nom wrapped_key.bin.

L'exemple de code Go suivant montre comment encapsuler le matériel de clé à l'aide de la bibliothèque tink-go :

package main

import (
    "bytes"
    "encoding/base64"
    "flag"
    "fmt"
    "log"

    "google.golang.org/protobuf/proto"
    "github.com/tink-crypto/tink-go/v2/hybrid"
    "github.com/tink-crypto/tink-go/v2/keyset"

    hpkepb "github.com/tink-crypto/tink-go/v2/proto/hpke_go_proto"
    tinkpb "github.com/tink-crypto/tink-go/v2/proto/tink_go_proto"
)

var (
    publicKeyB64Flag = flag.String("public_key", "", "Base64 encoded public key for wrapping.")
    targetKeyB64Flag = flag.String("target_key", "", "Base64 encoded 32-byte target key to be wrapped.")
)

func main() {
    flag.Parse()

    if *publicKeyB64Flag == "" {
        log.Fatal("-public_key is required")
    }
    if *targetKeyB64Flag == "" {
        log.Fatal("-target_key is required")
    }

    pkBytes, err := base64.StdEncoding.DecodeString(*publicKeyB64Flag)
    if err != nil {
        log.Fatalf("failed to decode public key: %v", err)
    }

    targetKey, err := base64.StdEncoding.DecodeString(*targetKeyB64Flag)
    if err != nil {
        log.Fatalf("failed to decode target key: %v", err)
    }

    hpkePubKey := &hpkepb.HpkePublicKey{
        Version: 0,
        Params: &hpkepb.HpkeParams{
            Kem:  hpkepb.HpkeKem_ML_KEM768,
            Kdf:  hpkepb.HpkeKdf_HKDF_SHA256,
            Aead: hpkepb.HpkeAead_AES_256_GCM,
        },
        PublicKey: pkBytes,
    }
    serializedPubKey, err := proto.Marshal(hpkePubKey)
    if err != nil {
        log.Fatalf("failed to marshal HPKE public key: %v", err)
    }

    ks := &tinkpb.Keyset{
        PrimaryKeyId: 1,
        Key: []*tinkpb.Keyset_Key{
            {
                KeyData: &tinkpb.KeyData{
                    TypeUrl:         "type.googleapis.com/google.crypto.tink.HpkePublicKey",
                    Value:           serializedPubKey,
                    KeyMaterialType: tinkpb.KeyData_ASYMMETRIC_PUBLIC,
                },
                Status:           tinkpb.KeyStatusType_ENABLED,
                KeyId:            1,
                OutputPrefixType: tinkpb.OutputPrefixType_RAW,
            },
        },
    }
    serializedKeyset, err := proto.Marshal(ks)
    if err != nil {
        log.Fatalf("failed to marshal keyset: %v", err)
    }

    // Create a KeysetHandle and retrieve the HybridEncrypt primitive.
    reader := keyset.NewBinaryReader(bytes.NewReader(serializedKeyset))
    handle, err := keyset.ReadWithNoSecrets(reader)
    if err != nil {
        log.Fatalf("failed to create keyset handle: %v", err)
    }

    enc, err := hybrid.NewHybridEncrypt(handle)
    if err != nil {
        log.Fatalf("failed to create hybrid encrypt primitive: %v", err)
    }

    // Perform the wrapping operation. Tink's HPKE implementation handles the
  // 'enc || ciphertext' concatenation automatically.
    wrappedKey, err := enc.Encrypt(targetKey, nil)
    if err != nil {
        log.Fatalf("failed to wrap key: %v", err)
    }

    fmt.Printf("Final wrappedKey (base64):\n%s\n", base64.StdEncoding.EncodeToString(wrappedKey))
}

Enregistrez la chaîne base64 de sortie ou décodez-la en fichier binaire : bash echo "BASE64_WRAPPED_KEY" | base64 --decode > wrapped_key.bin

Remarque : Pendant la version bêta, seules les clés pré-encapsulées peuvent être importées. L'encapsulation automatique des clés n'est pas prise en charge.

Importer la clé encapsulée

Importez la clé encapsulée préparée en tant que nouvelle version de votre clé cible.

gcloud

Exécutez la commande kms keys versions import :

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

Remplacez les éléments suivants :

• LOCATION : emplacement du trousseau de clés qui contient votre clé cible.
• KEY_RING : nom du trousseau de clés qui contient la clé cible.
• KEY_NAME : nom de votre clé cible.
• IMPORT_JOB : nom de votre job d'importation.
• ALGORITHM : algorithme du matériel de clé à importer.

REST

Appelez la méthode cryptoKeyVersions.import :

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

Remplacez les éléments suivants :

• PROJECT_ID : identifiant de votre projet Cloud KMS.
• LOCATION : emplacement du trousseau de clés qui contient votre clé cible.
• KEY_RING : nom du trousseau de clés qui contient la clé cible.
• KEY_NAME : nom de votre clé cible.
• TOKEN : jeton permettant d'authentifier la requête.
• IMPORT_JOB : identifiant du job d'importation correspondant.
• ALGORITHM : algorithme du matériel de clé à importer.
• PATH_TO_WRAPPED_KEY : chemin d'accès à votre clé encapsulée manuellement au format base64.

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 est 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 consoleGoogle Cloud ou de l'API Cloud Key Management Service.

Console

1. Ouvrez la page Gestion des clés dans la consoleGoogle 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 ou mettre à jour Google Cloud CLI.

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][api_importjob_fields_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 à ENABLED. 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é.

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

Si vous devez restaurer une version de clé précédemment importée qui est à l'état DESTROYED ou IMPORT_FAILED pour la remettre à l'état ENABLED, vous pouvez réimporter exactement le même matériel de clé.

La réimportation d'une version de clé détruite suit la même procédure que l'importation initiale, à l'aide du job d'importation d'origine ou d'un nouveau job d'importation (avec le même niveau de protection SOFTWARE).

Remarque : Vous ne pouvez pas réimporter une clé à l'aide d'une méthode à sécurité quantique si la version de clé d'origine a été importée à l'aide d'une méthode d'importation de clé basée sur RSA.