Cloud HSM

Cette rubrique présente Cloud HSM et vous explique comment créer et utiliser des clés de chiffrement protégées par HSM dans le service Cloud Key Management Service.

Qu'est-ce que Cloud HSM ?

Cloud HSM est un service de module de sécurité matériel sur le cloud qui permet d'héberger des clés de chiffrement et d'effectuer des opérations cryptographiques dans un cluster de modules HSM certifiés FIPS 140-2 niveau 3. La gestion de ce cluster HSM étant assurée par Google, vous n'avez pas à vous soucier des questions de mise en cluster, de scaling ni de déploiement de correctifs. Dans la mesure où Cloud HSM utilise Cloud KMS comme interface, vous pouvez tirer parti de l'ensemble des avantages et des fonctionnalités offerts par Cloud KMS.

Remarque : Lorsque vous utilisez des clés et des versions de clé basées sur HSM pour des opérations cryptographiques, le projet Google Cloud qui génère la requête de chiffrement entraîne une utilisation du quota d'opérations cryptographiques, et le projet Google Cloud qui contient les clés HSM entraîne une utilisation du quota de RPM pour HSM. Pour plus d'informations sur Cloud KMS, consultez la page Quotas.

Créer un trousseau de clés

Lorsque vous créez une clé, vous l'ajoutez à un trousseau dans un emplacement Google Cloud donné. Vous pouvez créer un trousseau de clés ou en utiliser un existant. Dans cette rubrique, vous allez créer un trousseau de clés et y ajouter une nouvelle clé.

Créez un trousseau de clés dans un emplacement Google Cloud compatible avec Cloud HSM.

Remarque : Des trousseaux de clés portant le même nom peuvent exister à différents emplacements. Vous devez donc toujours spécifier l'emplacement.

UI Web

1. Accédez à la page Clés de chiffrement dans Cloud Console.

   Accéder à la page Clés de chiffrement

2. Cliquez sur Créer un trousseau.

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

4. Dans la liste déroulante Key ring location (Emplacement du trousseau), sélectionnez un emplacement tel que "us-east1".

5. Cliquez sur Créer.

Ligne de commande

Pour utiliser Cloud KMS sur la ligne de commande, commencez par installer ou mettre à jour le SDK Cloud.

gcloud kms keyrings create key-ring \
    --location location

Remplacez key-ring par le nom du trousseau de clés. Remplacez location par l'emplacement Cloud KMS du trousseau de clés et de ses clés.

Pour en savoir plus sur toutes les options et valeurs possibles, exécutez la commande avec l'option --help.

C#

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

Afficher sur GitHub Commentaires

using Google.Api.Gax.ResourceNames;
using Google.Cloud.Kms.V1;

public class CreateKeyRingSample
{
    public KeyRing CreateKeyRing(
      string projectId = "my-project", string locationId = "us-east1",
      string id = "my-key-ring")
    {
        // Create the client.
        KeyManagementServiceClient client = KeyManagementServiceClient.Create();

        // Build the parent location name.
        LocationName locationName = new LocationName(projectId, locationId);

        // Build the key ring.
        KeyRing keyRing = new KeyRing { };

        // Call the API.
        KeyRing result = client.CreateKeyRing(locationName, id, keyRing);

        // Return the result.
        return result;
    }
}

Go

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

Afficher sur GitHub Commentaires

import (
	"context"
	"fmt"
	"io"

	kms "cloud.google.com/go/kms/apiv1"
	kmspb "google.golang.org/genproto/googleapis/cloud/kms/v1"
)

// createKeyRing creates a new ring to store keys on KMS.
func createKeyRing(w io.Writer, parent, id string) error {
	// parent := "projects/PROJECT_ID/locations/global"
	// id := "my-key-ring"

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

	// Build the request.
	req := &kmspb.CreateKeyRingRequest{
		Parent:    parent,
		KeyRingId: id,
	}

	// Call the API.
	result, err := client.CreateKeyRing(ctx, req)
	if err != nil {
		return fmt.Errorf("failed to create key ring: %v", err)
	}
	fmt.Fprintf(w, "Created key ring: %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.

Afficher sur GitHub Commentaires

import com.google.cloud.kms.v1.KeyManagementServiceClient;
import com.google.cloud.kms.v1.KeyRing;
import com.google.cloud.kms.v1.LocationName;
import java.io.IOException;

public class CreateKeyRing {

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

  // Create a new key ring.
  public void createKeyRing(String projectId, String locationId, 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 and location.
      LocationName locationName = LocationName.of(projectId, locationId);

      // Build the key ring to create.
      KeyRing keyRing = KeyRing.newBuilder().build();

      // Create the key ring.
      KeyRing createdKeyRing = client.createKeyRing(locationName, id, keyRing);
      System.out.printf("Created key ring %s%n", createdKeyRing.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.

Afficher sur GitHub Commentaires

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

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

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

// Build the parent location name
const locationName = client.locationPath(projectId, locationId);

async function createKeyRing() {
  const [keyRing] = await client.createKeyRing({
    parent: locationName,
    keyRingId: id,
  });

  console.log(`Created key ring: ${keyRing.name}`);
  return keyRing;
}

return createKeyRing();

PHP

Pour exécuter ce code, commencez par en apprendre plus sur l'utilisation de PHP sur Google Cloud, puis installez le SDK Cloud KMS pour PHP.

Afficher sur GitHub Commentaires

use Google\Cloud\Kms\V1\KeyManagementServiceClient;
use Google\Cloud\Kms\V1\KeyRing;

function create_key_ring_sample(
    string $projectId = 'my-project',
    string $locationId = 'us-east1',
    string $id = 'my-key-ring'
) {
    // Create the Cloud KMS client.
    $client = new KeyManagementServiceClient();

    // Build the parent location name.
    $locationName = $client->locationName($projectId, $locationId);

    // Build the key ring.
    $keyRing = new KeyRing();

    // Call the API.
    $createdKeyRing = $client->createKeyRing($locationName, $id, $keyRing);
    printf('Created key ring: %s' . PHP_EOL, $createdKeyRing->getName());
    return $createdKeyRing;
}

Python

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

Afficher sur GitHub Commentaires

def create_key_ring(project_id, location_id, id):
    """
    Creates a new key ring 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').
        id (string): ID of the key ring to create (e.g. 'my-key-ring').

    Returns:
        KeyRing: Cloud KMS key ring.

    """

    # Import the client library.
    from google.cloud import kms

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

    # Build the parent location name.
    location_name = f'projects/{project_id}/locations/{location_id}'

    # Build the key ring.
    key_ring = {}

    # Call the API.
    created_key_ring = client.create_key_ring(request={'parent': location_name, 'key_ring_id': id, 'key_ring': key_ring})
    print('Created key ring: {}'.format(created_key_ring.name))
    return created_key_ring

Ruby

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

Afficher sur GitHub Commentaires

# TODO(developer): uncomment these values before running the sample.
# project_id  = "my-project"
# location_id = "us-east1"
# id = "my-key-ring"

# Require the library.
require "google/cloud/kms"

# Create the client.
client = Google::Cloud::Kms.key_management_service

# Build the parent location name.
location_name = client.location_path project: project_id, location: location_id

# Build the key ring.
key_ring = {}

# Call the API.
created_key_ring = client.create_key_ring parent: location_name, key_ring_id: id, key_ring: key_ring
puts "Created key ring: #{created_key_ring.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.

curl "https://cloudkms.googleapis.com/v1/projects/project-id/locations/location-id/keyRings" \
    --request "POST" \
    --header "authorization: Bearer token" \
    --header "content-type: application/json" \
    --header "x-goog-user-project: project-id" \
    --data "{\"name\": {\"key-ring-name\": {}}}"

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

Créer une clé

Suivez ces étapes pour créer une clé Cloud HSM dans le trousseau et l'emplacement spécifiés.

UI Web

1. Accédez à la page Clés de chiffrement dans Cloud Console.

   Accéder à la page Clés de chiffrement

2. Cliquez sur le nom du trousseau de clés pour lequel vous souhaitez créer une clé.

3. Cliquez sur Créer une clé.

4. Dans la section Quel type de clé souhaitez-vous créer ?, sélectionnez Clé générée.

5. Dans le champ Nom de la clé, saisissez le nom de votre clé.

6. Cliquez sur le menu déroulant Niveau de protection, puis sélectionnez HSM.

7. Cliquez sur la liste déroulante Objectif et sélectionnez Chiffrement/déchiffrement symétriques.

8. Acceptez les valeurs par défaut pour Rotation period (Période de rotation) et Starting on (Rotation à partir du).

9. Cliquez sur Créer.

Ligne de commande

Pour utiliser Cloud KMS sur la ligne de commande, commencez par installer ou mettre à jour le SDK Cloud.

gcloud kms keys create key \
    --keyring key-ring \
    --location location \
    --purpose "encryption" \
    --protection-level "hsm"

Remplacez key par le nom de la nouvelle clé. Remplacez key-ring par le nom du trousseau de clés existant où sera située la clé. Remplacez location par l'emplacement Cloud KMS du trousseau de clés.

Pour en savoir plus sur toutes les options et valeurs possibles, exécutez la commande avec l'option --help.

C#

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

Afficher sur GitHub Commentaires

using Google.Cloud.Kms.V1;

public class CreateKeyHsmSample
{
    public CryptoKey CreateKeyHsm(
      string projectId = "my-project", string locationId = "us-east1", string keyRingId = "my-key-ring",
      string id = "my-hsm-encryption-key")
    {
        // Create the client.
        KeyManagementServiceClient client = KeyManagementServiceClient.Create();

        // Build the parent key ring name.
        KeyRingName keyRingName = new KeyRingName(projectId, locationId, keyRingId);

        // Build the key.
        CryptoKey key = new CryptoKey
        {
            Purpose = CryptoKey.Types.CryptoKeyPurpose.EncryptDecrypt,
            VersionTemplate = new CryptoKeyVersionTemplate
            {
                ProtectionLevel = ProtectionLevel.Hsm,
                Algorithm = CryptoKeyVersion.Types.CryptoKeyVersionAlgorithm.GoogleSymmetricEncryption,
            }
        };

        // Call the API.
        CryptoKey result = client.CreateCryptoKey(keyRingName, id, key);

        // Return the result.
        return result;
    }
}

Go

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

Afficher sur GitHub Commentaires

import (
	"context"
	"fmt"
	"io"

	kms "cloud.google.com/go/kms/apiv1"
	kmspb "google.golang.org/genproto/googleapis/cloud/kms/v1"
)

// createKeyHSM creates a new symmetric encrypt/decrypt key on Cloud KMS.
func createKeyHSM(w io.Writer, parent, id string) error {
	// parent := "projects/my-project/locations/us-east1/keyRings/my-key-ring"
	// id := "my-hsm-encryption-key"

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

	// Build the request.
	req := &kmspb.CreateCryptoKeyRequest{
		Parent:      parent,
		CryptoKeyId: id,
		CryptoKey: &kmspb.CryptoKey{
			Purpose: kmspb.CryptoKey_ENCRYPT_DECRYPT,
			VersionTemplate: &kmspb.CryptoKeyVersionTemplate{
				ProtectionLevel: kmspb.ProtectionLevel_HSM,
				Algorithm:       kmspb.CryptoKeyVersion_GOOGLE_SYMMETRIC_ENCRYPTION,
			},
		},
	}

	// Call the API.
	result, err := client.CreateCryptoKey(ctx, req)
	if err != nil {
		return fmt.Errorf("failed to create key: %v", 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.

Afficher sur GitHub Commentaires

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 CreateKeyHsm {

  public void createKeyHsm() 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-hsm-key";
    createKeyHsm(projectId, locationId, keyRingId, id);
  }

  // Create a new key that is stored in an HSM.
  public void createKeyHsm(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 hsm key to create.
      CryptoKey key =
          CryptoKey.newBuilder()
              .setPurpose(CryptoKeyPurpose.ENCRYPT_DECRYPT)
              .setVersionTemplate(
                  CryptoKeyVersionTemplate.newBuilder()
                      .setProtectionLevel(ProtectionLevel.HSM)
                      .setAlgorithm(CryptoKeyVersionAlgorithm.GOOGLE_SYMMETRIC_ENCRYPTION))
              .build();

      // Create the key.
      CryptoKey createdKey = client.createCryptoKey(keyRingName, id, key);
      System.out.printf("Created hsm 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.

Afficher sur GitHub Commentaires

//
// 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-hsm-encryption-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 createKeyHsm() {
  const [key] = await client.createCryptoKey({
    parent: keyRingName,
    cryptoKeyId: id,
    cryptoKey: {
      purpose: 'ENCRYPT_DECRYPT',
      versionTemplate: {
        algorithm: 'GOOGLE_SYMMETRIC_ENCRYPTION',
        protectionLevel: 'HSM',
      },
    },
  });

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

return createKeyHsm();

PHP

Pour exécuter ce code, commencez par en apprendre plus sur l'utilisation de PHP sur Google Cloud, puis installez le SDK Cloud KMS pour PHP.

Afficher sur GitHub Commentaires

use Google\Cloud\Kms\V1\CryptoKey;
use Google\Cloud\Kms\V1\CryptoKey\CryptoKeyPurpose;
use Google\Cloud\Kms\V1\CryptoKeyVersion\CryptoKeyVersionAlgorithm;
use Google\Cloud\Kms\V1\CryptoKeyVersionTemplate;
use Google\Cloud\Kms\V1\KeyManagementServiceClient;
use Google\Cloud\Kms\V1\ProtectionLevel;

function create_key_hsm_sample(
    string $projectId = 'my-project',
    string $locationId = 'us-east1',
    string $keyRingId = 'my-key-ring',
    string $id = 'my-hsm-key'
) {
    // Create the Cloud KMS client.
    $client = new KeyManagementServiceClient();

    // Build the parent key ring name.
    $keyRingName = $client->keyRingName($projectId, $locationId, $keyRingId);

    // Build the key.
    $key = (new CryptoKey())
        ->setPurpose(CryptoKeyPurpose::ENCRYPT_DECRYPT)
        ->setVersionTemplate((new CryptoKeyVersionTemplate())
            ->setAlgorithm(CryptoKeyVersionAlgorithm::GOOGLE_SYMMETRIC_ENCRYPTION)
            ->setProtectionLevel(ProtectionLevel::HSM)
        );

    // Call the API.
    $createdKey = $client->createCryptoKey($keyRingName, $id, $key);
    printf('Created hsm key: %s' . PHP_EOL, $createdKey->getName());
    return $createdKey;
}

Python

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

Afficher sur GitHub Commentaires

def create_key_hsm(project_id, location_id, key_ring_id, id):
    """
    Creates a new key in Cloud KMS backed by Cloud HSM.

    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').
        id (string): ID of the key to create (e.g. 'my-hsm-key').

    Returns:
        CryptoKey: Cloud KMS key.

    """

    # Import the client library.
    from google.cloud import kms

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

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

    # Build the key.
    purpose = kms.CryptoKey.CryptoKeyPurpose.ENCRYPT_DECRYPT
    algorithm = kms.CryptoKeyVersion.CryptoKeyVersionAlgorithm.GOOGLE_SYMMETRIC_ENCRYPTION
    protection_level = kms.ProtectionLevel.HSM
    key = {
        'purpose': purpose,
        'version_template': {
            'algorithm': algorithm,
            'protection_level': protection_level
        }
    }

    # Call the API.
    created_key = client.create_crypto_key(request={'parent': key_ring_name, 'crypto_key_id': id, 'crypto_key': key})
    print('Created hsm key: {}'.format(created_key.name))
    return created_key

Ruby

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

Afficher sur GitHub Commentaires

# TODO(developer): uncomment these values before running the sample.
# project_id  = "my-project"
# location_id = "us-east1"
# key_ring_id = "my-key-ring"
# id          = "my-hsm-key"

# Require the library.
require "google/cloud/kms"

# Create the client.
client = Google::Cloud::Kms.key_management_service

# Build the parent key ring name.
key_ring_name = client.key_ring_path project: project_id, location: location_id, key_ring: key_ring_id

# Build the key.
key = {
  purpose:          :ENCRYPT_DECRYPT,
  version_template: {
    algorithm:        :GOOGLE_SYMMETRIC_ENCRYPTION,
    protection_level: :HSM
  }
}

# Call the API.
created_key = client.create_crypto_key parent: key_ring_name, crypto_key_id: id, crypto_key: key
puts "Created hsm key: #{created_key.name}"

Chiffrer des données

Maintenant que vous disposez d'une clé, vous pouvez vous en servir pour chiffrer un texte ou un contenu binaire.

Ligne de commande

Pour utiliser Cloud KMS sur la ligne de commande, commencez par installer ou mettre à jour le SDK Cloud.

gcloud kms encrypt \
    --key key \
    --keyring key-ring \
    --location location  \
    --plaintext-file file-with-data-to-encrypt \
    --ciphertext-file file-to-store-encrypted-data

Remplacez key par le nom de la clé à utiliser pour le chiffrement. Remplacez key-ring par le nom du trousseau de clés où se trouve la clé. Remplacez location par l'emplacement Cloud KMS du trousseau de clés. Remplacez file-with-data-to-encrypt et file-to-store-encrypted-data par les chemins d'accès aux fichiers locaux pour la lecture des données en texte brut et l'enregistrement du résultat chiffré.

Pour en savoir plus sur toutes les options et valeurs possibles, exécutez la commande avec l'option --help.

C#

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

Afficher sur GitHub Commentaires

using Google.Cloud.Kms.V1;
using Google.Protobuf;
using System.Text;

public class EncryptSymmetricSample
{
    public byte[] EncryptSymmetric(
      string projectId = "my-project", string locationId = "us-east1", string keyRingId = "my-key-ring", string keyId = "my-key",
      string message = "Sample message")
    {
        // Create the client.
        KeyManagementServiceClient client = KeyManagementServiceClient.Create();

        // Build the key name.
        CryptoKeyName keyName = new CryptoKeyName(projectId, locationId, keyRingId, keyId);

        // Convert the message into bytes. Cryptographic plaintexts and
        // ciphertexts are always byte arrays.
        byte[] plaintext = Encoding.UTF8.GetBytes(message);

        // Call the API.
        EncryptResponse result = client.Encrypt(keyName, ByteString.CopyFrom(plaintext));

        // Return the ciphertext.
        return result.Ciphertext.ToByteArray();
    }
}

Go

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

Afficher sur GitHub Commentaires

import (
	"context"
	"fmt"
	"io"

	kms "cloud.google.com/go/kms/apiv1"
	kmspb "google.golang.org/genproto/googleapis/cloud/kms/v1"
)

// encryptSymmetric encrypts the input plaintext with the specified symmetric
// Cloud KMS key.
func encryptSymmetric(w io.Writer, name string, message string) error {
	// name := "projects/my-project/locations/us-east1/keyRings/my-key-ring/cryptoKeys/my-key"
	// message := "Sample message"

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

	// Convert the message into bytes. Cryptographic plaintexts and
	// ciphertexts are always byte arrays.
	plaintext := []byte(message)

	// Build the request.
	req := &kmspb.EncryptRequest{
		Name:      name,
		Plaintext: plaintext,
	}

	// Call the API.
	result, err := client.Encrypt(ctx, req)
	if err != nil {
		return fmt.Errorf("failed to encrypt: %v", err)
	}

	fmt.Fprintf(w, "Encrypted ciphertext: %s", result.Ciphertext)
	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.

Afficher sur GitHub Commentaires

import com.google.cloud.kms.v1.CryptoKeyName;
import com.google.cloud.kms.v1.EncryptResponse;
import com.google.cloud.kms.v1.KeyManagementServiceClient;
import com.google.protobuf.ByteString;
import java.io.IOException;

public class EncryptSymmetric {

  public void encryptSymmetric() 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 keyId = "my-key";
    String plaintext = "Plaintext to encrypt";
    encryptSymmetric(projectId, locationId, keyRingId, keyId, plaintext);
  }

  // Encrypt data with a given key.
  public void encryptSymmetric(
      String projectId, String locationId, String keyRingId, String keyId, String plaintext)
      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 key version name from the project, location, key ring, key,
      // and key version.
      CryptoKeyName keyVersionName = CryptoKeyName.of(projectId, locationId, keyRingId, keyId);

      // Encrypt the plaintext.
      EncryptResponse response = client.encrypt(keyVersionName, ByteString.copyFromUtf8(plaintext));
      System.out.printf("Ciphertext: %s%n", response.getCiphertext().toStringUtf8());
    }
  }
}

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.

Afficher sur GitHub Commentaires

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

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

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

// Build the key name
const keyName = client.cryptoKeyPath(projectId, locationId, keyRingId, keyId);

async function encryptSymmetric() {
  const [encryptResponse] = await client.encrypt({
    name: keyName,
    plaintext: plaintextBuffer,
  });

  const ciphertext = encryptResponse.ciphertext;

  console.log(`Ciphertext: ${ciphertext.toString('base64')}`);
  return ciphertext;
}

return encryptSymmetric();

PHP

Pour exécuter ce code, commencez par en apprendre plus sur l'utilisation de PHP sur Google Cloud, puis installez le SDK Cloud KMS pour PHP.

Afficher sur GitHub Commentaires

use Google\Cloud\Kms\V1\KeyManagementServiceClient;

function encrypt_symmetric_sample(
    string $projectId = 'my-project',
    string $locationId = 'us-east1',
    string $keyRingId = 'my-key-ring',
    string $keyId = 'my-key',
    string $plaintext = '...'
) {
    // Create the Cloud KMS client.
    $client = new KeyManagementServiceClient();

    // Build the key name.
    $keyName = $client->cryptoKeyName($projectId, $locationId, $keyRingId, $keyId);

    // Call the API.
    $encryptResponse = $client->encrypt($keyName, $plaintext);
    printf('Ciphertext: %s' . PHP_EOL, $encryptResponse->getCiphertext());
    return $encryptResponse;
}

Python

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

Afficher sur GitHub Commentaires

def encrypt_symmetric(project_id, location_id, key_ring_id, key_id, plaintext):
    """
    Encrypt plaintext using a symmetric key.

    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').
        key_id (string): ID of the key to use (e.g. 'my-key').
        plaintext (string): message to encrypt

    Returns:
        bytes: Encrypted ciphertext.

    """

    # Import the client library.
    from google.cloud import kms

    # Import base64 for printing the ciphertext.
    import base64

    # Convert the plaintext to bytes.
    plaintext_bytes = plaintext.encode('utf-8')

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

    # Build the key name.
    key_name = client.crypto_key_path(project_id, location_id, key_ring_id, key_id)

    # Call the API.
    encrypt_response = client.encrypt(request={'name': key_name, 'plaintext': plaintext_bytes})
    print('Ciphertext: {}'.format(base64.b64encode(encrypt_response.ciphertext)))
    return encrypt_response

Ruby

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

Afficher sur GitHub Commentaires

# TODO(developer): uncomment these values before running the sample.
# project_id  = "my-project"
# location_id = "us-east1"
# key_ring_id = "my-key-ring"
# key_id      = "my-key"
# plaintext  = "..."

# Require the library.
require "google/cloud/kms"

# Create the client.
client = Google::Cloud::Kms.key_management_service

# Build the parent key name.
key_name = client.crypto_key_path project:    project_id,
                                  location:   location_id,
                                  key_ring:   key_ring_id,
                                  crypto_key: key_id

# Call the API.
response = client.encrypt name: key_name, plaintext: plaintext
puts "Ciphertext: #{Base64.strict_encode64 response.ciphertext}"

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.

Lorsque vous utilisez JSON et l'API REST, le contenu doit être codé en base64 avant de pouvoir être chiffré par Cloud KMS.

Conseil : Vous pouvez encoder ou décoder des données en base64 à l'aide de la commande base64 sous Linux ou macOS, ou de la commande Base64.exe sous Windows. Les langages de programmation et de script incluent généralement des bibliothèques pour le codage en base64. Pour obtenir des exemples de ligne de commande, consultez l'article Encoder en Base64 dans la documentation de l'API Cloud Vision.

Pour chiffrer des données, effectuez une requête POST et fournissez les informations de projet et de clé appropriées, puis spécifiez le texte encodé en base64 à chiffrer dans le champ plaintext du corps de la requête.

curl "https://cloudkms.googleapis.com/v1/projects/project-id/locations/location/keyRings/key-ring-name/cryptoKeys/key-name:encrypt" \
  --request "POST" \
  --header "authorization: Bearer token" \
  --header "content-type: application/json" \
  --data "{\"plaintext\": \"base64-encoded-input\"}"

Voici un exemple de charge utile avec des données encodées en base64 :

{
  "plaintext": "U3VwZXIgc2VjcmV0IHRleHQgdGhhdCBtdXN0IGJlIGVuY3J5cHRlZAo=",
}

Déchiffrer le texte chiffré

Pour déchiffrer le contenu chiffré, vous devez utiliser la même clé que celle qui a servi à chiffrer ce contenu.

Ligne de commande

Pour utiliser Cloud KMS sur la ligne de commande, commencez par installer ou mettre à jour le SDK Cloud.

gcloud kms decrypt \
    --key key \
    --keyring key-ring \
    --location location  \
    --ciphertext-file file-path-with-encrypted-data \
    --plaintext-file file-path-to-store-plaintext

Remplacez key par le nom de la clé à utiliser pour le déchiffrement. Remplacez key-ring par le nom du trousseau de clés où sera située la clé. Remplacez location par l'emplacement Cloud KMS du trousseau de clés. Remplacez file-path-with-encrypted-data et file-path-to-store-plaintext par les chemins d'accès aux fichiers locaux pour la lecture des données chiffrées et l'enregistrement du résultat déchiffré.

Pour en savoir plus sur toutes les options et valeurs possibles, exécutez la commande avec l'option --help.

C#

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

Afficher sur GitHub Commentaires

using Google.Cloud.Kms.V1;
using Google.Protobuf;
using System.Text;

public class DecryptSymmetricSample
{
    public string DecryptSymmetric(
      string projectId = "my-project", string locationId = "us-east1", string keyRingId = "my-key-ring", string keyId = "my-key",
      byte[] ciphertext = null)
    {
        // Create the client.
        KeyManagementServiceClient client = KeyManagementServiceClient.Create();

        // Build the key name.
        CryptoKeyName keyName = new CryptoKeyName(projectId, locationId, keyRingId, keyId);

        // Call the API.
        DecryptResponse result = client.Decrypt(keyName, ByteString.CopyFrom(ciphertext));

        // Get the plaintext. Cryptographic plaintexts and ciphertexts are
        // always byte arrays.
        byte[] plaintext = result.Plaintext.ToByteArray();

        // Return the result.
        return Encoding.UTF8.GetString(plaintext);
    }
}

Go

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

Afficher sur GitHub Commentaires

import (
	"context"
	"fmt"
	"io"

	kms "cloud.google.com/go/kms/apiv1"
	kmspb "google.golang.org/genproto/googleapis/cloud/kms/v1"
)

// decryptSymmetric will decrypt the input ciphertext bytes using the specified symmetric key.
func decryptSymmetric(w io.Writer, name string, ciphertext []byte) error {
	// name := "projects/my-project/locations/us-east1/keyRings/my-key-ring/cryptoKeys/my-key"
	// ciphertext := []byte("...")  // result of a symmetric encryption call

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

	// Build the request.
	req := &kmspb.DecryptRequest{
		Name:       name,
		Ciphertext: ciphertext,
	}

	// Call the API.
	result, err := client.Decrypt(ctx, req)
	if err != nil {
		return fmt.Errorf("failed to decrypt ciphertext: %v", err)
	}
	fmt.Fprintf(w, "Decrypted plaintext: %s", result.Plaintext)
	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.

Afficher sur GitHub Commentaires

import com.google.cloud.kms.v1.CryptoKeyName;
import com.google.cloud.kms.v1.DecryptResponse;
import com.google.cloud.kms.v1.KeyManagementServiceClient;
import com.google.protobuf.ByteString;
import java.io.IOException;

public class DecryptSymmetric {

  public void decryptSymmetric() 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 keyId = "my-key";
    byte[] ciphertext = null;
    decryptSymmetric(projectId, locationId, keyRingId, keyId, ciphertext);
  }

  // Decrypt data that was encrypted using a symmetric key.
  public void decryptSymmetric(
      String projectId, String locationId, String keyRingId, String keyId, byte[] ciphertext)
      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 key version name from the project, location, key ring, and
      // key.
      CryptoKeyName keyName = CryptoKeyName.of(projectId, locationId, keyRingId, keyId);

      // Decrypt the response.
      DecryptResponse response = client.decrypt(keyName, ByteString.copyFrom(ciphertext));
      System.out.printf("Plaintext: %s%n", response.getPlaintext().toStringUtf8());
    }
  }
}

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.

Afficher sur GitHub Commentaires

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

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

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

// Build the key name
const keyName = client.cryptoKeyPath(projectId, locationId, keyRingId, keyId);

async function decryptSymmetric() {
  const [result] = await client.decrypt({
    name: keyName,
    ciphertext: ciphertext,
  });

  const plaintext = result.plaintext.toString('utf8');

  console.log(`Plaintext: ${plaintext}`);
  return plaintext;
}

return decryptSymmetric();

PHP

Pour exécuter ce code, commencez par en apprendre plus sur l'utilisation de PHP sur Google Cloud, puis installez le SDK Cloud KMS pour PHP.

Afficher sur GitHub Commentaires

use Google\Cloud\Kms\V1\KeyManagementServiceClient;

function decrypt_symmetric_sample(
    string $projectId = 'my-project',
    string $locationId = 'us-east1',
    string $keyRingId = 'my-key-ring',
    string $keyId = 'my-key',
    string $ciphertext = '...'
) {
    // Create the Cloud KMS client.
    $client = new KeyManagementServiceClient();

    // Build the key name.
    $keyName = $client->cryptoKeyName($projectId, $locationId, $keyRingId, $keyId);

    // Call the API.
    $decryptResponse = $client->decrypt($keyName, $ciphertext);
    printf('Plaintext: %s' . PHP_EOL, $decryptResponse->getPlaintext());
    return $decryptResponse;
}

Python

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

Afficher sur GitHub Commentaires

def decrypt_symmetric(project_id, location_id, key_ring_id, key_id, ciphertext):
    """
    Decrypt the ciphertext using the symmetric key

    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').
        key_id (string): ID of the key to use (e.g. 'my-key').
        ciphertext (bytes): Encrypted bytes to decrypt.

    Returns:
        DecryptResponse: Response including plaintext.

    """

    # Import the client library.
    from google.cloud import kms

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

    # Build the key name.
    key_name = client.crypto_key_path(project_id, location_id, key_ring_id, key_id)

    # Call the API.
    decrypt_response = client.decrypt(request={'name': key_name, 'ciphertext': ciphertext})
    print('Plaintext: {}'.format(decrypt_response.plaintext))
    return decrypt_response

Ruby

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

Afficher sur GitHub Commentaires

# TODO(developer): uncomment these values before running the sample.
# project_id  = "my-project"
# location_id = "us-east1"
# key_ring_id = "my-key-ring"
# key_id      = "my-key"
# ciphertext  = "..."

# Require the library.
require "google/cloud/kms"

# Create the client.
client = Google::Cloud::Kms.key_management_service

# Build the parent key name.
key_name = client.crypto_key_path project:    project_id,
                                  location:   location_id,
                                  key_ring:   key_ring_id,
                                  crypto_key: key_id

# Call the API.
response = client.decrypt name: key_name, ciphertext: ciphertext
puts "Plaintext: #{response.plaintext}"

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.

Le texte déchiffré qui est renvoyé au format JSON depuis Cloud KMS est encodé en base64.

Conseil : Vous pouvez encoder ou décoder des données en base64 à l'aide de la commande base64 sous Linux ou macOS, ou de la commande Base64.exe sous Windows. Les langages de programmation et de script incluent généralement des bibliothèques pour le codage en base64. Pour obtenir des exemples de ligne de commande, consultez l'article Encoder en Base64 dans la documentation de l'API Cloud Vision.

Pour déchiffrer des données chiffrées, effectuez une requête POST et fournissez les informations de projet et de clé appropriées, puis spécifiez le texte chiffré (cipher) à déchiffrer dans le champ ciphertext du corps de la requête.

curl "https://cloudkms.googleapis.com/v1/projects/project-id/locations/location/keyRings/key-ring-name/cryptoKeys/key-name:decrypt" \
  --request "POST" \
  --header "authorization: Bearer token" \
  --header "content-type: application/json" \
  --data "{\"ciphertext\": \"encrypted-content\"}"

Voici un exemple de charge utile avec des données encodées en base64 :

{
  "ciphertext": "CiQAhMwwBo61cHas7dDgifrUFs5zNzBJ2uZtVFq4ZPEl6fUVT4kSmQ...",
}

Étapes suivantes

• L'exemple de chiffrement présenté dans cette rubrique utilisait une clé symétrique dotée du niveau de protection HSM. Pour chiffrer à l'aide d'une clé asymétrique présentant le niveau de protection HSM, suivez les étapes décrites dans la page Chiffrer et déchiffrer des données avec une clé asymétrique en y apportant les modifications suivantes :

  • Créez le trousseau de clés dans l'une des régions disponibles pour Cloud HSM.
  • Créez la clé avec le niveau de protection HSM.

• Pour effectuer une signature à courbe elliptique ou une signature RSA à l'aide d'une clé asymétrique dotée du niveau de protection HSM, suivez les étapes décrites dans la page Créer et valider des signatures en y apportant les modifications suivantes :

  • Créez le trousseau de clés dans l'une des régions disponibles pour Cloud HSM.
  • Créez la clé avec le niveau de protection HSM.

• Commencez à utiliser l'API.

• Consultez la documentation de référence sur l'API Cloud KMS.

• Lisez les guides pratiques pour découvrir comment créer des clés, effectuer des rotations de clés et définir des autorisations sur les clés.

• Familiarisez-vous avec les concepts pour en savoir plus sur la hiérarchie des objets, les états des clés et la rotation des clés.

• Apprenez-en plus sur la journalisation dans Cloud KMS. Notez que la journalisation est basée sur les opérations et s'applique aux clés présentant les deux niveaux de protection Logiciel et HSM.

Limites connues

• La taille de bloc est limitée à 16 384 octets (contre 64 Kio pour les clés logicielles Cloud KMS) pour le texte brut et le texte chiffré fournis par l'utilisateur, y compris les données authentifiées supplémentaires.

• Il est possible que Cloud HSM ne soit pas disponible dans certains emplacements multirégionaux ou birégionaux. Pour plus d'informations, consultez la section Régions disponibles pour Cloud HSM.

• Si vous utilisez des clés Cloud HSM avec des intégrations de clés de chiffrement gérées par le client (CMEK, Customer-Managed Encryption Key) dans d'autres services Google Cloud, les emplacements que vous utilisez pour les services doivent correspondre exactement à ceux de vos clés Cloud HSM. Cela s'applique aux emplacements régionaux, birégionaux et multirégionaux.

  Pour en savoir plus sur les intégrations de CMEK, consultez la section correspondante du document Chiffrement au repos.

• Actuellement, les opérations de clé portant sur des clés stockées dans Cloud HSM peuvent entraîner une latence nettement supérieure à celle obtenue avec les clés logicielles Cloud KMS.

Autres options HSM

Google Cloud propose des options HSM supplémentaires, telles que l'unité de location unique, pour certains clients. Renseignez-vous auprès de votre responsable de compte pour en savoir plus.