Cloud HSM

במסמך הזה מפורטת סקירה כללית על Cloud HSM ומוסבר איך ליצור מפתחות הצפנה שמוגנים על ידי HSM ב-Cloud Key Management Service ולהשתמש בהם.

מה זה Cloud HSM?

‫Cloud HSM הוא שירות של מודול אבטחת חומרה (HSM) שמתארח בענן, ומאפשר לארח מפתחות הצפנה ולבצע פעולות קריפטוגרפיות באשכול של מודולי HSM עם אישור FIPS 140-2 ברמה 3. ‫Google מנהלת את אשכול ה-HSM בשבילכם, כך שאתם לא צריכים לדאוג לגבי אשכולות, שינוי גודל או תיקון. מכיוון ש-Cloud HSM משתמש ב-Cloud KMS כחלק הקדמי שלו, אתם יכולים ליהנות מכל היתרונות והתכונות ש-Cloud KMS מספק.

הערה: כשמשתמשים במפתחות ובגרסאות מפתחות שמגובים על ידי HSM לפעולות קריפטוגרפיות, הפרויקט Google Cloud שמבצע את הבקשה הקריפטוגרפית צורך מכסת שימוש של פעולות קריפטוגרפיות, והפרויקט Google Cloudשמכיל את מפתחות ה-HSM צורך מכסת שימוש של מכסת QPM של HSM. מידע נוסף על Cloud KMS מופיע במאמר בנושא מכסות.

יצירת אוסף מפתחות

כשיוצרים מפתח, מוסיפים אותו לאוסף מפתחות במיקום Google Cloud מסוים. אתם יכולים ליצור אוסף מפתחות חדש או להשתמש באוסף מפתחות קיים. בנושא הזה, תלמדו איך ליצור אוסף מפתחות חדש ולהוסיף לו מפתח חדש.

יוצרים אוסף מפתחות ב Google Cloud מיקום שתומך ב-Cloud HSM.

הערה: יכולים להיות אוספי מפתחות עם אותו שם במיקומים שונים, ולכן תמיד צריך לציין את המיקום.

המסוף

1. נכנסים לדף Key Management במסוף Google Cloud .

   כניסה לדף Key Management

2. לוחצים על Create key ring.

3. בשדה שם אוסף המפתחות, מזינים שם לאוסף המפתחות.

4. בקטע מיקום אוסף מפתחות, בוחרים מיקום כמו "us-east1".

   הערה: בחרו מיקום שקרוב למשאבים שאתם רוצים להגן עליהם. כדי להשתמש ב-CMEK, אוסף המפתחות צריך להיות באותו מיקום שבו נמצאים המשאבים שאתם משתמשים בהם. במפתחות Cloud EKM, המיקום צריך להיות קרוב פיזית לספק של מנהל המפתחות החיצוני (EKM).

5. לוחצים על יצירה.

gcloud

1. במסוף Google Cloud , מפעילים את Cloud Shell.

   הפעלת Cloud Shell

2. בסביבה שלכם, מריצים את הפקודה gcloud kms keyrings create:

   gcloud kms keyrings create KEY_RING \
       --location LOCATION
   

   מחליפים את מה שכתוב בשדות הבאים:

   • ‫KEY_RING: השם של אוסף המפתחות שמכיל את המפתח.
   • ‫LOCATION: המיקום ב-Cloud KMS שבו נמצא אוסף המפתחות.

   כדי לקבל מידע על כל הדגלים והערכים האפשריים, מריצים את הפקודה עם הדגל --help.

C#

כדי להריץ את הקוד הזה, קודם צריך להגדיר סביבת פיתוח בשפת C# ‎ ולהתקין את Cloud KMS C# SDK.

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

כדי להריץ את הקוד הזה, קודם צריך להגדיר סביבת פיתוח של Go ולהתקין את Cloud KMS Go SDK.

import (
	"context"
	"fmt"
	"io"

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

// 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: %w", err)
	}
	defer client.Close()

	// 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: %w", err)
	}
	fmt.Fprintf(w, "Created key ring: %s\n", result.Name)
	return nil
}

Java

כדי להריץ את הקוד הזה, קודם צריך להגדיר סביבת פיתוח של Java ולהתקין את Java SDK של Cloud KMS.

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

כדי להריץ את הקוד הזה, קודם צריך להגדיר סביבת פיתוח של Node.js ולהתקין את Cloud KMS Node.js SDK.

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

כדי להריץ את הקוד הזה, קודם צריך לקרוא על שימוש ב-PHP ב- Google Cloud ולהתקין את Cloud KMS PHP SDK.

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

function create_key_ring(
    string $projectId = 'my-project',
    string $locationId = 'us-east1',
    string $id = 'my-key-ring'
): KeyRing {
    // 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.
    $createKeyRingRequest = (new CreateKeyRingRequest())
        ->setParent($locationName)
        ->setKeyRingId($id)
        ->setKeyRing($keyRing);
    $createdKeyRing = $client->createKeyRing($createKeyRingRequest);
    printf('Created key ring: %s' . PHP_EOL, $createdKeyRing->getName());

    return $createdKeyRing;
}

Python

כדי להריץ את הקוד הזה, קודם צריך להגדיר סביבת פיתוח של Python ולהתקין את Cloud KMS Python SDK.

from google.cloud import kms


def create_key_ring(
    project_id: str, location_id: str, key_ring_id: str
) -> kms.CryptoKey:
    """
    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').
        key_ring_id (string): ID of the key ring to create (e.g. 'my-key-ring').

    Returns:
        KeyRing: Cloud KMS key ring.

    """

    # 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": key_ring_id,
            "key_ring": key_ring,
        }
    )
    print(f"Created key ring: {created_key_ring.name}")
    return created_key_ring

Ruby

כדי להריץ את הקוד הזה, קודם צריך להגדיר סביבת פיתוח של Ruby ולהתקין את Cloud KMS Ruby SDK.

# 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

בדוגמאות האלה נעשה שימוש ב-curl כלקוח HTTP כדי להדגים את השימוש ב-API. מידע נוסף על בקרת גישה זמין במאמר גישה ל-Cloud KMS API.

curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings?key_ring_id=KEY_RING" \
    --request "POST" \
    --header "authorization: Bearer TOKEN"

מחליפים את מה שכתוב בשדות הבאים:

• ‫PROJECT_ID: מזהה הפרויקט שמכיל את אוסף המפתחות.
• ‫KEY_RING: השם של אוסף המפתחות שמכיל את המפתח.
• ‫LOCATION: המיקום ב-Cloud KMS שבו נמצא אוסף המפתחות.

מידע נוסף מופיע במאמרי העזרה של KeyRing.create API.

יצירת מפתח

כדי ליצור מפתח Cloud HSM באוסף המפתחות ובמיקום שצוינו:

המסוף

1. נכנסים לדף Key Management במסוף Google Cloud .

   כניסה אל Key Management

2. לוחצים על השם של אוסף המפתחות שבו רוצים ליצור מפתח.

3. לוחצים על Create key.

4. בקטע What type of key do you want to create? (איזה סוג מפתח רוצים ליצור?), בוחרים באפשרות Generated key (מפתח שנוצר).

5. בשדה שם המפתח, מזינים את השם של המפתח.

6. לוחצים על התפריט הנפתח רמת ההגנה ובוחרים באפשרות HSM או Single-tenant HSM.

7. אם בחרתם באפשרות Single-tenant HSM, בוחרים את המופע של Single-tenant HSM שבו רוצים ליצור את המפתח.

8. לוחצים על התפריט הנפתח Purpose (מטרה) ובוחרים באפשרות Symmetric encrypt/decrypt (הצפנה/פענוח סימטריים).

9. מאשרים את ערכי ברירת המחדל של Rotation period ו-Starting on.

10. לוחצים על יצירה.

gcloud

כדי להשתמש ב-Cloud KMS בשורת הפקודה, קודם צריך להתקין את הגרסה העדכנית של Google Cloud CLI או לשדרג אליה.

כדי ליצור מפתח Cloud HSM עם כמה דיירים, מריצים את הפקודה kms keys create עם רמת ההגנה hsm.

gcloud kms keys create KEY_NAME \
    --keyring KEY_RING \
    --location LOCATION \
    --purpose "encryption" \
    --protection-level "hsm"

מחליפים את מה שכתוב בשדות הבאים:

• ‫KEY_NAME: השם שרוצים להשתמש בו עבור המפתח.
• ‫KEY_RING: השם של אוסף המפתחות שבו רוצים ליצור את המפתח.
• ‫LOCATION: המיקום של אוסף המפתחות.

כדי לקבל מידע על כל הדגלים והערכים האפשריים, מריצים את הפקודה עם הדגל --help.

כדי ליצור מפתח Cloud HSM בדייר יחיד, מריצים את הפקודה kms keys create עם רמת ההגנה hsm-single-tenant ומציינים את מופע Cloud HSM בדייר יחיד שבו רוצים ליצור את המפתח. מופע Cloud HSM עם דייר יחיד צריך להיות באותו מיקום שבו נמצא אוסף המפתחות.

gcloud kms keys create KEY_NAME \
    --keyring KEY_RING \
    --location LOCATION \
    --purpose "encryption" \
    --protection-level "hsm-single-tenant" \
    --crypto-key-backend="projects/INSTANCE_PROJECT/locations/LOCATION/singleTenantHsmInstances/INSTANCE_NAME"

מחליפים את מה שכתוב בשדות הבאים:

• ‫KEY_NAME: השם שרוצים להשתמש בו עבור המפתח.
• ‫KEY_RING: השם של אוסף המפתחות שבו רוצים ליצור את המפתח.
• ‫LOCATION: המיקום של אוסף המפתחות.
• ‫PROTECTION_LEVEL: רמת ההגנה של המפתח שרוצים ליצור.
• ‫INSTANCE_PROJECT: המזהה של הפרויקט שבו נמצא המכונה של Cloud HSM בדייר יחיד.
• ‫INSTANCE_NAME: השם של מכונת Cloud HSM לדייר יחיד שבה רוצים ליצור את המפתח. מידע נוסף על מכונות Cloud HSM לדייר יחיד זמין במאמר יצירה וניהול של מכונת Cloud HSM לדייר יחיד.

C#

כדי להריץ את הקוד הזה, קודם צריך להגדיר סביבת פיתוח ב-C# ‎ ולהתקין את Cloud KMS C# SDK.

using Google.Cloud.Kms.V1;
using Google.Protobuf.WellKnownTypes;

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

            // Optional: customize how long key versions should be kept before destroying.
            DestroyScheduledDuration = new Duration
            {
                Seconds = 24 * 60 * 60,
            }
        };

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

        // Return the result.
        return result;
    }
}

Go

כדי להריץ את הקוד הזה, קודם צריך להגדיר סביבת פיתוח של Go ולהתקין את Cloud KMS Go SDK.

import (
	"context"
	"fmt"
	"io"
	"time"

	kms "cloud.google.com/go/kms/apiv1"
	"cloud.google.com/go/kms/apiv1/kmspb"
	"google.golang.org/protobuf/types/known/durationpb"
)

// 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: %w", err)
	}
	defer client.Close()

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

			// Optional: customize how long key versions should be kept before destroying.
			DestroyScheduledDuration: durationpb.New(24 * time.Hour),
		},
	}

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

כדי להריץ את הקוד הזה, קודם צריך להגדיר סביבת פיתוח של Java ולהתקין את Java SDK של Cloud KMS.

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 com.google.protobuf.Duration;
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))

              // Optional: customize how long key versions should be kept before destroying.
              .setDestroyScheduledDuration(Duration.newBuilder().setSeconds(24 * 60 * 60))
              .build();

      // Create the key.
      CryptoKey createdKey = client.createCryptoKey(keyRingName, id, key);
      System.out.printf("Created hsm key %s%n", createdKey.getName());
    }
  }
}

Node.js

כדי להריץ את הקוד הזה, קודם צריך להגדיר סביבת פיתוח של Node.js ולהתקין את Cloud KMS Node.js SDK.

//
// 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',
      },

      // Optional: customize how long key versions should be kept before
      // destroying.
      destroyScheduledDuration: {seconds: 60 * 60 * 24},
    },
  });

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

return createKeyHsm();

PHP

כדי להריץ את הקוד הזה, קודם צריך ללמוד על שימוש ב-PHP ב- Google Cloud ולהתקין את Cloud KMS PHP SDK.

use Google\Cloud\Kms\V1\Client\KeyManagementServiceClient;
use Google\Cloud\Kms\V1\CreateCryptoKeyRequest;
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\ProtectionLevel;
use Google\Protobuf\Duration;

function create_key_hsm(
    string $projectId = 'my-project',
    string $locationId = 'us-east1',
    string $keyRingId = 'my-key-ring',
    string $id = 'my-hsm-key'
): CryptoKey {
    // 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)
        )

        // Optional: customize how long key versions should be kept before destroying.
        ->setDestroyScheduledDuration((new Duration())
            ->setSeconds(24 * 60 * 60)
        );

    // Call the API.
    $createCryptoKeyRequest = (new CreateCryptoKeyRequest())
        ->setParent($keyRingName)
        ->setCryptoKeyId($id)
        ->setCryptoKey($key);
    $createdKey = $client->createCryptoKey($createCryptoKeyRequest);
    printf('Created hsm key: %s' . PHP_EOL, $createdKey->getName());

    return $createdKey;
}

Python

כדי להריץ את הקוד הזה, קודם צריך להגדיר סביבת פיתוח של Python ולהתקין את Cloud KMS Python SDK.

import datetime

from google.cloud import kms
from google.protobuf import duration_pb2  # type: ignore


def create_key_hsm(
    project_id: str, location_id: str, key_ring_id: str, key_id: str
) -> kms.CryptoKey:
    """
    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').
        key_id (string): ID of the key to create (e.g. 'my-hsm-key').

    Returns:
        CryptoKey: Cloud KMS key.

    """

    # 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,
        },
        # Optional: customize how long key versions should be kept before
        # destroying.
        "destroy_scheduled_duration": duration_pb2.Duration().FromTimedelta(
            datetime.timedelta(days=1)
        ),
    }

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

Ruby

כדי להריץ את הקוד הזה, קודם צריך להגדיר סביבת פיתוח של Ruby ולהתקין את Cloud KMS Ruby SDK.

# 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
  },

  # Optional: customize how long key versions should be kept before destroying.
  destroy_scheduled_duration: {
    seconds: 24 * 60 * 60
  }
}

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

API

בדוגמאות האלה משתמשים ב-curl כצד הלקוח ב-HTTP כדי להדגים את השימוש ב-API. מידע נוסף על בקרת גישה זמין במאמר גישה ל-Cloud KMS API.

כדי ליצור מפתח Cloud HSM רב-דיירים, משתמשים בשיטה CryptoKey.create עם רמת ההגנה HSM:

curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys?crypto_key_id=KEY_NAME" \
    --request "POST" \
    --header "authorization: Bearer TOKEN" \
    --header "content-type: application/json" \
    --data '{"purpose": "ENCRYPT_DECRYPT", "versionTemplate": {
        "protectionLevel": "HSM", "algorithm": "ALGORITHM" }}'

מחליפים את מה שכתוב בשדות הבאים:

• ‫PROJECT_ID: מזהה הפרויקט שמכיל את אוסף המפתחות.
• ‫LOCATION: המיקום ב-Cloud KMS שבו נמצא אוסף המפתחות.
• ‫KEY_RING: השם של אוסף המפתחות שמכיל את המפתח.
• ‫KEY_NAME: שם המפתח.
• ‫ALGORITHM: האלגוריתם שבו רוצים להשתמש, לדוגמה GOOGLE_SYMMETRIC_ENCRYPTION. במאמר מטרות ואלגוריתמים של מפתחות מפורטים כל האלגוריתמים הנתמכים.

כדי ליצור מפתח Cloud HSM לדייר יחיד, משתמשים ב-method‏ CryptoKey.create עם רמת ההגנה HSM_SINGLE_TENANT:

curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys?crypto_key_id=KEY_NAME" \
    --request "POST" \
    --header "authorization: Bearer TOKEN" \
    --header "content-type: application/json" \
    --data '{"purpose": "ENCRYPT_DECRYPT", "versionTemplate": {
        "protectionLevel": "HSM_SINGLE_TENANT", "algorithm": "ALGORITHM",
        "cryptoKeyBackend": "projects/INSTANCE_PROJECT/locations/LOCATION/singleTenantHsmInstances/INSTANCE_NAME" }}'

מחליפים את מה שכתוב בשדות הבאים:

• ‫PROJECT_ID: מזהה הפרויקט שמכיל את אוסף המפתחות.
• ‫LOCATION: המיקום ב-Cloud KMS שבו נמצא אוסף המפתחות.
• ‫KEY_RING: השם של אוסף המפתחות שמכיל את המפתח.
• ‫KEY_NAME: שם המפתח.
• ‫ALGORITHM: האלגוריתם שבו רוצים להשתמש, לדוגמה GOOGLE_SYMMETRIC_ENCRYPTION. כדי לראות את כל האלגוריתמים הנתמכים, אפשר לעיין במאמר בנושא מטרות ואלגוריתמים של מפתחות.
• ‫INSTANCE_PROJECT: המזהה של הפרויקט שבו נמצא מופע Cloud HSM עם דייר יחיד.
• ‫INSTANCE_NAME: השם של מופע Single-tenant Cloud HSM שבו רוצים ליצור את המפתח. מידע נוסף על מכונות Cloud HSM לדייר יחיד זמין במאמר יצירה וניהול של מכונת Cloud HSM לדייר יחיד.

הצפנת נתונים

עכשיו, כשיש לכם מפתח, אתם יכולים להשתמש בו כדי להצפין טקסט או תוכן בינארי.

gcloud

כדי להשתמש ב-Cloud KMS בשורת הפקודה, קודם צריך להתקין את הגרסה העדכנית של Google Cloud CLI או לשדרג אליה.

gcloud kms encrypt \
    --key KEY_NAME \
    --keyring KEY_RING \
    --location LOCATION  \
    --plaintext-file FILE_TO_ENCRYPT \
    --ciphertext-file ENCRYPTED_OUTPUT

מחליפים את מה שכתוב בשדות הבאים:

• ‫KEY_NAME: השם של המפתח שרוצים להשתמש בו להצפנה.
• ‫KEY_RING: השם של אוסף המפתחות שמכיל את המפתח.
• ‫LOCATION: המיקום ב-Cloud KMS שבו נמצא אוסף המפתחות.
• ‫FILE_TO_ENCRYPT: הנתיב לקובץ שרוצים להצפין.
• ‫ENCRYPTED_OUTPUT: הנתיב שבו רוצים לשמור את הפלט המוצפן.

כדי לקבל מידע על כל הדגלים והערכים האפשריים, מריצים את הפקודה עם הדגל --help.

C#

כדי להריץ את הקוד הזה, קודם צריך להגדיר סביבת פיתוח בשפת C# ‎ ולהתקין את ה-SDK של Cloud KMS בשפת C# ‎.

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

כדי להריץ את הקוד הזה, קודם צריך להגדיר סביבת פיתוח של Go ולהתקין את Cloud KMS Go SDK.

import (
	"context"
	"fmt"
	"hash/crc32"
	"io"

	kms "cloud.google.com/go/kms/apiv1"
	"cloud.google.com/go/kms/apiv1/kmspb"
	"google.golang.org/protobuf/types/known/wrapperspb"
)

// 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: %w", err)
	}
	defer client.Close()

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

	// Optional but recommended: Compute plaintext's CRC32C.
	crc32c := func(data []byte) uint32 {
		t := crc32.MakeTable(crc32.Castagnoli)
		return crc32.Checksum(data, t)
	}
	plaintextCRC32C := crc32c(plaintext)

	// Build the request.
	req := &kmspb.EncryptRequest{
		Name:            name,
		Plaintext:       plaintext,
		PlaintextCrc32C: wrapperspb.Int64(int64(plaintextCRC32C)),
	}

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

	// Optional, but recommended: perform integrity verification on result.
	// For more details on ensuring E2E in-transit integrity to and from Cloud KMS visit:
	// https://cloud.google.com/kms/docs/data-integrity-guidelines
	if result.VerifiedPlaintextCrc32C == false {
		return fmt.Errorf("Encrypt: request corrupted in-transit")
	}
	if int64(crc32c(result.Ciphertext)) != result.CiphertextCrc32C.Value {
		return fmt.Errorf("Encrypt: response corrupted in-transit")
	}

	fmt.Fprintf(w, "Encrypted ciphertext: %s", result.Ciphertext)
	return nil
}

Java

כדי להריץ את הקוד הזה, קודם צריך להגדיר סביבת פיתוח ב-Java ולהתקין את Cloud KMS Java SDK.

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

כדי להריץ את הקוד הזה, קודם צריך להגדיר סביבת פיתוח של Node.js ולהתקין את Cloud KMS Node.js SDK.

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

// Optional, but recommended: compute plaintext's CRC32C.
const crc32c = require('fast-crc32c');
const plaintextCrc32c = crc32c.calculate(plaintextBuffer);

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

  const ciphertext = encryptResponse.ciphertext;

  // Optional, but recommended: perform integrity verification on encryptResponse.
  // For more details on ensuring E2E in-transit integrity to and from Cloud KMS visit:
  // https://cloud.google.com/kms/docs/data-integrity-guidelines
  if (!encryptResponse.verifiedPlaintextCrc32c) {
    throw new Error('Encrypt: request corrupted in-transit');
  }
  if (
    crc32c.calculate(ciphertext) !==
    Number(encryptResponse.ciphertextCrc32c.value)
  ) {
    throw new Error('Encrypt: response corrupted in-transit');
  }

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

return encryptSymmetric();

PHP

כדי להריץ את הקוד הזה, קודם צריך לקרוא על שימוש ב-PHP ב- Google Cloud ולהתקין את Cloud KMS PHP SDK.

use Google\Cloud\Kms\V1\Client\KeyManagementServiceClient;
use Google\Cloud\Kms\V1\EncryptRequest;

function encrypt_symmetric(
    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.
    $encryptRequest = (new EncryptRequest())
        ->setName($keyName)
        ->setPlaintext($plaintext);
    $encryptResponse = $client->encrypt($encryptRequest);
    printf('Ciphertext: %s' . PHP_EOL, $encryptResponse->getCiphertext());

    return $encryptResponse;
}

Python

כדי להריץ את הקוד הזה, קודם צריך להגדיר סביבת פיתוח ב-Python ולהתקין את Cloud KMS Python SDK.

# Import base64 for printing the ciphertext.
import base64

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


def encrypt_symmetric(
    project_id: str, location_id: str, key_ring_id: str, key_id: str, plaintext: str
) -> bytes:
    """
    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.

    """

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

    # Optional, but recommended: compute plaintext's CRC32C.
    # See crc32c() function defined below.
    plaintext_crc32c = crc32c(plaintext_bytes)

    # 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,
            "plaintext_crc32c": plaintext_crc32c,
        }
    )

    # Optional, but recommended: perform integrity verification on encrypt_response.
    # For more details on ensuring E2E in-transit integrity to and from Cloud KMS visit:
    # https://cloud.google.com/kms/docs/data-integrity-guidelines
    if not encrypt_response.verified_plaintext_crc32c:
        raise Exception("The request sent to the server was corrupted in-transit.")
    if not encrypt_response.ciphertext_crc32c == crc32c(encrypt_response.ciphertext):
        raise Exception(
            "The response received from the server was corrupted in-transit."
        )
    # End integrity verification

    print(f"Ciphertext: {base64.b64encode(encrypt_response.ciphertext)}")
    return encrypt_response


def crc32c(data: bytes) -> int:
    """
    Calculates the CRC32C checksum of the provided data.

    Args:
        data: the bytes over which the checksum should be calculated.

    Returns:
        An int representing the CRC32C checksum of the provided bytes.
    """
    import crcmod  # type: ignore

    crc32c_fun = crcmod.predefined.mkPredefinedCrcFun("crc-32c")
    return crc32c_fun(data)

Ruby

כדי להריץ את הקוד הזה, קודם צריך להגדיר סביבת פיתוח של Ruby ולהתקין את Cloud KMS Ruby SDK.

# 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

בדוגמאות האלה נעשה שימוש ב-curl כלקוח HTTP כדי להדגים את השימוש ב-API. מידע נוסף על בקרת גישה זמין במאמר גישה ל-Cloud KMS API.

כשמשתמשים ב-JSON וב-API בארכיטקטורת REST, צריך לקודד את התוכן ב-base64 לפני שאפשר להצפין אותו באמצעות Cloud KMS.

טיפ: אפשר להשתמש בפקודה base64 ב-Linux או ב-macOS, או בפקודה Base64.exe ב-Windows, כדי לקודד או לפענח נתונים בפורמט Base64. שפות תכנות וסקריפטים כוללות בדרך כלל ספריות לקידוד base64. דוגמאות לשורות פקודה זמינות במאמר קידוד Base64 במסמכי התיעוד של Cloud Vision API.

כדי להצפין נתונים, שולחים בקשת POST ומספקים את פרטי הפרויקט והמפתח המתאימים, ומציינים את הטקסט בקידוד base64 שרוצים להצפין בשדה plaintext של גוף הבקשה.

curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME:encrypt" \
  --request "POST" \
  --header "authorization: Bearer TOKEN" \
  --header "content-type: application/json" \
  --data "{\"plaintext\": \"PLAINTEXT_TO_ENCRYPT\"}"

מחליפים את מה שכתוב בשדות הבאים:

• ‫PROJECT_ID: המזהה של הפרויקט שמכיל את אוסף המפתחות ואת המפתח שרוצים להשתמש בהם להצפנה.
• ‫LOCATION: המיקום ב-Cloud KMS שבו נמצא אוסף המפתחות.
• ‫KEY_RING: אוסף המפתחות שמכיל את המפתח שרוצים להשתמש בו להצפנה.
• ‫KEY_NAME: השם של המפתח שרוצים להשתמש בו להצפנה.
• ‫PLAINTEXT_TO_ENCRYPT: נתוני הטקסט הפשוט שרוצים להצפין. לפני שמפעילים את ה-method‏ encrypt, צריך לקודד את הטקסט הרגיל בפורמט Base64.

דוגמה למטען ייעודי (payload) עם נתונים בקידוד base64:

{
  "plaintext": "U3VwZXIgc2VjcmV0IHRleHQgdGhhdCBtdXN0IGJlIGVuY3J5cHRlZAo=",
}

פענוח טקסט מוצפן

כדי לפענח תוכן מוצפן, צריך להשתמש באותו מפתח ששימש להצפנת התוכן.

gcloud

כדי להשתמש ב-Cloud KMS בשורת הפקודה, קודם צריך להתקין את הגרסה העדכנית של Google Cloud CLI או לשדרג אליה.

gcloud kms decrypt \
    --key KEY_NAME \
    --keyring KEY_RING \
    --location LOCATION  \
    --ciphertext-file FILE_TO_DECRYPT \
    --plaintext-file DECRYPTED_OUTPUT

מחליפים את מה שכתוב בשדות הבאים:

• ‫KEY_NAME: השם של המפתח שרוצים להשתמש בו לפענוח.
• ‫KEY_RING: השם של אוסף המפתחות שמכיל את המפתח.
• ‫LOCATION: המיקום ב-Cloud KMS שבו נמצא אוסף המפתחות.
• ‫FILE_TO_DECRYPT: הנתיב לקובץ שרוצים לפענח.
• ‫DECRYPTED_OUTPUT: הנתיב שבו רוצים לשמור את הפלט המפוענח.

כדי לקבל מידע על כל הדגלים והערכים האפשריים, מריצים את הפקודה עם הדגל --help.

C#

כדי להריץ את הקוד הזה, קודם צריך להגדיר סביבת פיתוח בשפת C# ‎ ולהתקין את ה-SDK של Cloud KMS בשפת C# ‎.

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

כדי להריץ את הקוד הזה, קודם צריך להגדיר סביבת פיתוח של Go ולהתקין את Cloud KMS Go SDK.

import (
	"context"
	"fmt"
	"hash/crc32"
	"io"

	kms "cloud.google.com/go/kms/apiv1"
	"cloud.google.com/go/kms/apiv1/kmspb"
	"google.golang.org/protobuf/types/known/wrapperspb"
)

// 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: %w", err)
	}
	defer client.Close()

	// Optional, but recommended: Compute ciphertext's CRC32C.
	crc32c := func(data []byte) uint32 {
		t := crc32.MakeTable(crc32.Castagnoli)
		return crc32.Checksum(data, t)
	}
	ciphertextCRC32C := crc32c(ciphertext)

	// Build the request.
	req := &kmspb.DecryptRequest{
		Name:             name,
		Ciphertext:       ciphertext,
		CiphertextCrc32C: wrapperspb.Int64(int64(ciphertextCRC32C)),
	}

	// Call the API.
	result, err := client.Decrypt(ctx, req)
	if err != nil {
		return fmt.Errorf("failed to decrypt ciphertext: %w", err)
	}

	// Optional, but recommended: perform integrity verification on result.
	// For more details on ensuring E2E in-transit integrity to and from Cloud KMS visit:
	// https://cloud.google.com/kms/docs/data-integrity-guidelines
	if int64(crc32c(result.Plaintext)) != result.PlaintextCrc32C.Value {
		return fmt.Errorf("Decrypt: response corrupted in-transit")
	}

	fmt.Fprintf(w, "Decrypted plaintext: %s", result.Plaintext)
	return nil
}

Java

כדי להריץ את הקוד הזה, קודם צריך להגדיר סביבת פיתוח של Java ולהתקין את Java SDK של Cloud KMS.

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

כדי להריץ את הקוד הזה, קודם צריך להגדיר סביבת פיתוח של Node.js ולהתקין את Cloud KMS Node.js SDK.

//
// 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';
// Ciphertext must be either a Buffer object or a base-64 encoded string
// 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);

// Optional, but recommended: compute ciphertext's CRC32C.
const crc32c = require('fast-crc32c');
const ciphertextCrc32c = crc32c.calculate(ciphertext);

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

  // Optional, but recommended: perform integrity verification on decryptResponse.
  // For more details on ensuring E2E in-transit integrity to and from Cloud KMS visit:
  // https://cloud.google.com/kms/docs/data-integrity-guidelines
  if (
    crc32c.calculate(decryptResponse.plaintext) !==
    Number(decryptResponse.plaintextCrc32c.value)
  ) {
    throw new Error('Decrypt: response corrupted in-transit');
  }

  const plaintext = decryptResponse.plaintext.toString();

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

return decryptSymmetric();

PHP

כדי להריץ את הקוד הזה, קודם צריך לקרוא על שימוש ב-PHP ב- Google Cloud ולהתקין את Cloud KMS PHP SDK.

use Google\Cloud\Kms\V1\Client\KeyManagementServiceClient;
use Google\Cloud\Kms\V1\DecryptRequest;

function decrypt_symmetric(
    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.
    $decryptRequest = (new DecryptRequest())
        ->setName($keyName)
        ->setCiphertext($ciphertext);
    $decryptResponse = $client->decrypt($decryptRequest);
    printf('Plaintext: %s' . PHP_EOL, $decryptResponse->getPlaintext());

    return $decryptResponse;
}

Python

כדי להריץ את הקוד הזה, קודם צריך להגדיר סביבת פיתוח של Python ולהתקין את Cloud KMS Python SDK.

from google.cloud import kms


def decrypt_symmetric(
    project_id: str, location_id: str, key_ring_id: str, key_id: str, ciphertext: bytes
) -> kms.DecryptResponse:
    """
    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.

    """

    # 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)

    # Optional, but recommended: compute ciphertext's CRC32C.
    # See crc32c() function defined below.
    ciphertext_crc32c = crc32c(ciphertext)

    # Call the API.
    decrypt_response = client.decrypt(
        request={
            "name": key_name,
            "ciphertext": ciphertext,
            "ciphertext_crc32c": ciphertext_crc32c,
        }
    )

    # Optional, but recommended: perform integrity verification on decrypt_response.
    # For more details on ensuring E2E in-transit integrity to and from Cloud KMS visit:
    # https://cloud.google.com/kms/docs/data-integrity-guidelines
    if not decrypt_response.plaintext_crc32c == crc32c(decrypt_response.plaintext):
        raise Exception(
            "The response received from the server was corrupted in-transit."
        )
    # End integrity verification

    print(f"Plaintext: {decrypt_response.plaintext!r}")
    return decrypt_response


def crc32c(data: bytes) -> int:
    """
    Calculates the CRC32C checksum of the provided data.
    Args:
        data: the bytes over which the checksum should be calculated.
    Returns:
        An int representing the CRC32C checksum of the provided bytes.
    """
    import crcmod  # type: ignore

    crc32c_fun = crcmod.predefined.mkPredefinedCrcFun("crc-32c")
    return crc32c_fun(data)

Ruby

כדי להריץ את הקוד הזה, קודם צריך להגדיר סביבת פיתוח של Ruby ולהתקין את Cloud KMS Ruby SDK.

# 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

בדוגמאות האלה נעשה שימוש ב-curl כלקוח HTTP כדי להדגים את השימוש ב-API. מידע נוסף על בקרת גישה זמין במאמר גישה ל-Cloud KMS API.

הטקסט המפוענח שמוחזר ב-JSON מ-Cloud KMS מקודד ב-Base64.

טיפ: אפשר להשתמש בפקודה base64 ב-Linux או ב-macOS, או בפקודה Base64.exe ב-Windows, כדי לקודד או לפענח נתונים בפורמט Base64. שפות תכנות וסקריפטים כוללות בדרך כלל ספריות לקידוד base64. דוגמאות לשורות פקודה זמינות במאמר קידוד Base64 במסמכי התיעוד של Cloud Vision API.

כדי לפענח נתונים מוצפנים, שולחים בקשת POST, מציינים את הפרויקט המתאים, מזינים את פרטי המפתח ומציינים את הטקסט המוצפן (שנקרא גם טקסט מוצפן) שרוצים לפענח בשדה ciphertext של גוף הבקשה.

curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME:decrypt" \
  --request "POST" \
  --header "authorization: Bearer TOKEN" \
  --header "content-type: application/json" \
  --data "{\"ciphertext\": \"ENCRYPTED_DATA\"}"

מחליפים את מה שכתוב בשדות הבאים:

• ‫PROJECT_ID: מזהה הפרויקט שמכיל את אוסף המפתחות ואת המפתח שבו רוצים להשתמש לפענוח.
• ‫LOCATION: המיקום ב-Cloud KMS שבו נמצא אוסף המפתחות.
• ‫KEY_RING: אוסף המפתחות שמכיל את המפתח שרוצים להשתמש בו לפענוח.
• ‫KEY_NAME: שם המפתח שבו רוצים להשתמש לפענוח.
• ‫ENCRYPTED_DATA: הנתונים המוצפנים שרוצים לפענח.

דוגמה למטען ייעודי עם נתונים שמקודדים ב-base64:

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

השלבים הבאים

• בדוגמה להצפנה שמופיעה בנושא הזה נעשה שימוש במפתח סימטרי עם רמת ההגנה של HSM. כדי להצפין באמצעות מפתח אסימטרי עם רמת ההגנה של HSM, פועלים לפי השלבים במאמר הצפנה ופענוח של נתונים באמצעות מפתח אסימטרי עם השינויים הבאים:

  • יוצרים את אוסף המפתחות באחד מהאזורים הנתמכים ב-Cloud HSM.
  • יוצרים את המפתח עם רמת ההגנה HSM.

• כדי להשתמש במפתח אסימטרי עם רמת ההגנה של HSM לחתימה על עקומה אליפטית או לחתימת RSA, פועלים לפי השלבים שמפורטים במאמר יצירה ואימות של חתימות, עם השינויים הבאים:

  • יוצרים את אוסף המפתחות באחד מהאזורים הנתמכים ב-Cloud HSM.
  • יוצרים את המפתח עם רמת ההגנה HSM.

• מתחילים להשתמש ב-API.

• מאמרי העזרה של Cloud KMS API

• במדריכים מוסבר איך ליצור מפתחות, להחליף אותם ולהגדיר להם הרשאות.

• כדאי לקרוא את המאמר מושגים כדי להבין טוב יותר את היררכיית האובייקטים, את מצבי המפתח ואת רוטציית המפתחות.

• מידע ולמידה על רישום ביומן ב-Cloud KMS. שימו לב שהרישום ביומן מבוסס על פעולות, והוא חל על מפתחות עם רמות הגנה של HSM ושל תוכנה.

• במאמר בנושא ארכיטקטורת Cloud HSM מוסבר איך Cloud HSM מגן על הנתונים שלכם.

מגבלות ידועות

• גודל ההודעה מוגבל ל-8KiB (בניגוד ל-64KiB למפתחות תוכנה של Cloud KMS) לטקסט פשוט ולמידע מוצפן (ciphertext) שסופקו על ידי המשתמש, כולל נתונים מאומתים נוספים.

• שירות Cloud HSM לא זמין במספר אזורים. במאמר מיקומים של Cloud KMS מופיעה רשימה של כל המיקומים שתומכים ב-Multi-tenant Cloud HSM. כדי לראות אותם, צריך לבחור באפשרות Supports multi-tenant HSM במסנן HSM support.

• ‫Cloud HSM עם דייר יחיד זמין בחלק מהמיקומים שבהם Cloud HSM עם כמה דיירים זמין. רשימה של כל המיקומים שתומכים ב-Cloud HSM עם דייר יחיד מופיעה במאמר מיקומים ב-Cloud KMS. כדי לראות את הרשימה, בוחרים באפשרות Supports single-tenant HSM במסנן HSM support.

• אם אתם משתמשים במפתחות Cloud HSM עם שילובים של מפתחות הצפנה בניהול הלקוח (CMEK) בשירותים אחרים של Google Cloud , המיקומים שבהם אתם משתמשים בשירותים חייבים להתאים בדיוק למיקומים של מפתחות Cloud HSM. העיקרון הזה חל על מיקומים אזוריים, על מיקומים בשני אזורים ועל מיקומים במספר אזורים.

  מידע נוסף על שילובי CMEK זמין בקטע הרלוונטי במאמר בנושא הצפנה במנוחה.

• פעולות במפתחות אסימטריים שמאוחסנים ב-Cloud HSM עלולות לגרום לזמן אחזור ארוך יותר בהשוואה לשימוש במפתחות תוכנה של Cloud KMS.

Bare Metal Rack HSM

Google Cloud מציע אפשרויות נוספות של HSM, כמו דיירות יחידה. ‫Bare Metal Rack HSM זמין ללקוחות שרוצים לארח את ה-HSM שלהם במרחב ש-Google מספקת. למידע נוסף, פנו לאיש הקשר האחראי לחשבון.