Importer une version de clé dans Cloud KMS

Ce guide vous 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 Importer une clé.

Vous pouvez suivre la procédure décrite dans ce guide 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é, faciliter le nettoyage après le test et vous assurer que vous disposez des autorisations IAM (Identity and Access Management) 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

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.

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.

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

1. 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 des deux rôles prédéfinis suivants :

   • roles/editor
   • roles/cloudkms.importer

   Pour en savoir plus sur les rôles et 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.

• Si vous souhaitez autoriser la Google Cloud CLI à encapsuler automatiquement vos clés avant de les transmettre à Google Cloud, vous devez installer la bibliothèque de cryptographie Pyca sur votre système local. La bibliothèque Pyca est utilisée par la tâche d'importation qui enveloppe et protège la clé en local avant de l'envoyer à Google Cloud.
• Si vous souhaitez encapsuler vos clés manuellement, vous devez configurer OpenSSL pour l'encapsulation manuelle des clés.

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 créés ou importés, les éléments suivants ne peuvent pas être modifiés :

• Le niveau de protection indique si la clé persiste dans le logiciel, dans un HSM multitenant, dans un HSM à locataire unique 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é ont le 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 afin de créer des versions de cette clé. Toutes les versions d'une clé ont la même fonction.

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 ce guide.

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

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 ce guide, 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 ce guide, 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 dans un trousseau de clés à l'aide de la Google Cloud CLI ou de la console Google Cloud .

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,