Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

Cloud HSM

本文提供 Cloud HSM 總覽，並說明如何在 Cloud Key Management Service 中建立及使用防護等級為 HSM 的加密金鑰。

什麼是 Cloud HSM？

Cloud HSM 是雲端託管硬體安全性模組 (HSM) 服務，可讓您託管加密金鑰，並在 FIPS 140-2 第 3 級認證的 HSM 叢集中執行加密編譯作業。Google 可代管 HSM 叢集，這樣您就不需要擔心分群、資源調度或修補的問題。由於 Cloud HSM 使用 Cloud KMS 做為前端，因此您可以利用 Cloud KMS 提供的所有便利性與功能。

建立金鑰環

建立金鑰時，請將金鑰新增至指定 Google Cloud位置的金鑰環。您可以建立新的金鑰環，或使用現有的金鑰環。在本主題中，您將建立新的金鑰環，並在其中新增金鑰。

在支援 Cloud HSM 的 Google Cloud 位置建立金鑰環。

控制台

前往 Google Cloud 控制台的「Key Management」頁面。

前往「金鑰管理」
按一下 [Create key ring] (建立金鑰環)。
在「金鑰環名稱」中輸入金鑰環的名稱。
針對「Key ring location」(金鑰環位置)，選取位置，例如 "us-east1"。

注意： 請選擇靠近要保護資源的位置。如要使用 CMEK，金鑰環應與您使用的資源位於相同位置。如果是 Cloud EKM 金鑰，位置必須與外部金鑰管理 (EKM) 供應商的實體位置相近。
點選「建立」。

gcloud

在 Google Cloud 控制台中啟用 Cloud Shell。

啟用 Cloud Shell
在環境中執行 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 開發環境，然後安裝 Cloud KMS Java SDK。

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

如要執行這段程式碼，請先瞭解如何在 Google Cloud上使用 PHP，並安裝 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：包含金鑰環的專案 ID。
KEY_RING：金鑰所屬金鑰環的名稱。
LOCATION：金鑰環的 Cloud KMS 位置。

詳情請參閱 KeyRing.create API 說明文件。

建立金鑰

請按照下列步驟，在指定的金鑰環和位置建立 Cloud HSM 金鑰。

控制台

前往 Google Cloud 控制台的「Key Management」頁面。

前往「金鑰管理」頁面
找出您要在哪個金鑰環中建立金鑰，然後按一下該金鑰環名稱。
按一下 [Create key] (建立金鑰)。
在「您要建立哪種類型的金鑰？」中，選擇「產生的金鑰」。
在「Key name」(金鑰名稱) 欄位中，輸入金鑰的名稱。
按一下「Protection level」(防護等級) 下拉式選單，然後選取「HSM」或「Single-tenant HSM」(單一租戶 HSM)。
如果選取「單一租戶 HSM」，請選取要建立金鑰的「單一租戶 HSM 執行個體」。
按一下 [Purpose] (目的) 下拉式清單，並選取 [對稱式加密/解密] (Symmetric encrypt/decrypt)。
接受「Rotation period」(輪替週期) 和「Starting on」(開始日期) 的預設值。
點選「建立」。

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 執行個體所在的專案 ID。
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 開發環境，然後安裝 Cloud KMS Java SDK。

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

如要執行這段程式碼，請先瞭解如何在 Google Cloud上使用 PHP，並安裝 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;

Cloud HSM 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

什麼是 Cloud HSM？

建立金鑰環

控制台

gcloud

C#

Go

Java

Node.js

PHP

Python

Ruby

API

建立金鑰

控制台

gcloud

C#

Go

Java

Node.js

PHP

Cloud HSM