Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

销毁和恢复密钥版本

本页面介绍如何安排永久销毁 Cloud Key Management Service 密钥版本。在 Cloud KMS 中，用于加密、解密、签署和验证数据的加密密钥材料存储在密钥版本中。一个密钥具有零个或多个密钥版本。当您轮替密钥时，会创建新的密钥版本。

销毁密钥版本意味着密钥材料将被永久删除。销毁密钥版本时，密钥名称和密钥版本号等其他详细信息不会被删除。销毁密钥后，使用该密钥版本加密的数据将无法解密。

唯一的例外是密钥重新导入，该功能允许您通过提供相同的原始密钥材料来恢复先前导入的密钥。

由于密钥销毁通常是不可逆的，因此 Cloud KMS 不允许您立即销毁密钥版本。相反，您需要安排销毁密钥版本。密钥版本会保持已安排销毁状态一段时间（可配置）。在已安排销毁期间，您可以恢复密钥版本以取消销毁。

默认的已安排销毁时长为 30 天。您可以在创建密钥期间为密钥设置自定义的已安排销毁时长。您的组织可以通过在组织政策中设置每个密钥的最小安排销毁时长 限制来强制执行最小安排销毁时长。

您还可以使用 Identity and Access Management (IAM) 管理对密钥的访问权限。 IAM 操作会在数秒内达成一致。如需了解更多信息，请参阅使用 IAM。

您还可以暂时停用密钥版本。我们建议您在安排销毁密钥版本之前先停用密钥版本，以确保密钥可以安全销毁。根据您的组织政策，您可能需要先停用密钥版本，然后才能安排销毁。如需详细了解如何使用组织政策控制密钥版本销毁，请参阅控制密钥版本销毁。

在本文档的其余部分中，安排销毁密钥称为销毁密钥，即使销毁不是立即执行的也是如此。

准备工作

了解风险

销毁密钥版本是一项永久性操作。销毁仍需要的密钥版本存在以下风险：

服务中断：如果您销毁启动容器或实例所需的密钥，您的服务或应用可能会变得不可用。
数据永久丢失：如果您销毁用于加密数据的密钥，该数据将变得不可用。使用已销毁的密钥加密的数据被视为“加密粉碎”。在某些情况下，销毁密钥可能会导致加密资源被永久删除。
监管或合规性问题：如果您销毁访问受保留期限限制的数据所需的密钥，并且销毁时间在保留期限结束之前，则您可能违反了监管或合规性要求。

所需的角色

如需获得销毁和恢复密钥版本所需的权限，请让您的管理员为您授予密钥的Cloud KMS Admin (roles/cloudkms.admin) IAM 角色。如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

检查密钥版本是否正在使用

在销毁密钥版本之前，请完成以下步骤以查看密钥版本是否正在使用：

查看密钥使用情况跟踪详细信息 for the key. 如果要销毁的密钥版本保护了任何资源，请使用其他密钥版本重新加密这些资源。

**注意**：密钥使用情况跟踪详细信息可能会延迟或不完整。请熟悉此数据的限制。
为可能使用密钥版本的任何服务或应用启用日志。
在包含密钥的 Cloud KMS 项目中启用日志。
停用密钥版本。停用密钥版本可防止使用该密钥版本。停用密钥版本后，任何使用该密钥版本的尝试都会失败。
监控日志，直到您确定没有应用或服务仍依赖于您停用的密钥版本。如果有任何错误表明无法访问密钥版本，请将应用或资源配置为使用其他密钥版本。

在销毁密钥版本之前，您需要监控日志的时间长短取决于密钥的类型、使用模式和敏感度级别。例如，在销毁每季度运行一次的进程中使用的密钥版本之前，请保持密钥版本处于停用状态，直到该进程成功完成。
根据任何适用的合规性要求检查密钥的使用情况。例如，密钥版本和使用该密钥版本加密的数据可能受数据保留期限的限制。

这些步骤有助于您确定密钥是否可能仍需要使用；但是，它们无法保证密钥版本不再需要使用。您的组织应实施程序和准则，以确保密钥版本销毁不会造成负面影响。

销毁密钥版本

您可以销毁已启用或已停用的密钥版本。

控制台

在 Google Cloud 控制台中，前往 密钥管理 页面。

前往 Key Management
选中要安排销毁的密钥版本旁边的复选框。
点击标头中的销毁。
在确认提示中输入密钥名称，然后点击安排销毁 。

gcloud

如需在命令行上使用 Cloud KMS，请先安装或升级到最新版本的 Google Cloud CLI。

gcloud kms keys versions destroy KEY_VERSION \
    --key KEY_NAME \
    --keyring KEY_RING \
    --location LOCATION

替换以下内容：

KEY_VERSION：您要销毁的密钥版本的版本号。
KEY_NAME：您要销毁密钥版本的密钥的名称。
KEY_RING：包含密钥的密钥环的名称。
LOCATION：密钥环的 Cloud KMS 位置。

如需了解所有标志和可能值，请使用 --help 标志运行命令。

C#

要运行此代码，请先设置 C# 开发环境并安装 Cloud KMS C# SDK。


using Google.Cloud.Kms.V1;

public class DestroyKeyVersionSample
{
    public CryptoKeyVersion DestroyKeyVersion(
      string projectId = "my-project", string locationId = "us-east1", string keyRingId = "my-key-ring", string keyId = "my-key", string keyVersionId = "123")
    {
        // Create the client.
        KeyManagementServiceClient client = KeyManagementServiceClient.Create();

        // Build the key version name.
        CryptoKeyVersionName keyVersionName = new CryptoKeyVersionName(projectId, locationId, keyRingId, keyId, keyVersionId);

        // Call the API.
        CryptoKeyVersion result = client.DestroyCryptoKeyVersion(keyVersionName);

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

// destroyKeyVersion marks a specified key version for deletion. The key can be
// restored if requested within 24 hours.
func destroyKeyVersion(w io.Writer, name string) error {
	// name := "projects/my-project/locations/us-east1/keyRings/my-key-ring/cryptoKeys/my-key/cryptoKeyVersions/123"

	// 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.DestroyCryptoKeyVersionRequest{
		Name: name,
	}

	// Call the API.
	result, err := client.DestroyCryptoKeyVersion(ctx, req)
	if err != nil {
		return fmt.Errorf("failed to destroy key version: %w", err)
	}
	fmt.Fprintf(w, "Destroyed key version: %s\n", result)
	return nil
}

Java

要运行此代码，请先设置 Java 开发环境并安装 Cloud KMS Java SDK。

import com.google.cloud.kms.v1.CryptoKeyVersion;
import com.google.cloud.kms.v1.CryptoKeyVersionName;
import com.google.cloud.kms.v1.KeyManagementServiceClient;
import java.io.IOException;

public class DestroyKeyVersion {

  public void destroyKeyVersion() 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 keyVersionId = "123";
    destroyKeyVersion(projectId, locationId, keyRingId, keyId, keyVersionId);
  }

  // Schedule destruction of the given key version.
  public void destroyKeyVersion(
      String projectId, String locationId, String keyRingId, String keyId, String keyVersionId)
      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.
      CryptoKeyVersionName keyVersionName =
          CryptoKeyVersionName.of(projectId, locationId, keyRingId, keyId, keyVersionId);

      // Destroy the key version.
      CryptoKeyVersion response = client.destroyCryptoKeyVersion(keyVersionName);
      System.out.printf("Destroyed key version: %s%n", response.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 keyId = 'my-key';
// const versionId = '123';

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

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

// Build the key version name
const versionName = client.cryptoKeyVersionPath(
  projectId,
  locationId,
  keyRingId,
  keyId,
  versionId
);

async function destroyKeyVersion() {
  const [version] = await client.destroyCryptoKeyVersion({
    name: versionName,
  });

  console.log(`Destroyed key version: ${version.name}`);
  return version;
}

return destroyKeyVersion();

PHP

要运行此代码，请先了解如何在上使用 PHP Google Cloud 并安装 Cloud KMS PHP SDK。

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

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

    // Build the key version name.
    $keyVersionName = $client->cryptoKeyVersionName($projectId, $locationId, $keyRingId, $keyId, $versionId);

    // Call the API.
    $destroyCryptoKeyVersionRequest = (new DestroyCryptoKeyVersionRequest())
        ->setName($keyVersionName);
    $destroyedVersion = $client->destroyCryptoKeyVersion($destroyCryptoKeyVersionRequest);
    printf('Destroyed key version: %s' . PHP_EOL, $destroyedVersion->getName());

    return $destroyedVersion;
}

Python

要运行此代码，请先设置 Python 开发环境并安装 Cloud KMS Python SDK。

from google.cloud import kms


def destroy_key_version(
    project_id: str, location_id: str, key_ring_id: str, key_id: str, version_id: str
) -> kms.CryptoKeyVersion:
    """
    Schedule destruction of the given key version.

    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').
        version_id (string): ID of the key version to destroy (e.g. '1').

    Returns:
        CryptoKeyVersion: The version.

    """

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

    # Build the key version name.
    key_version_name = client.crypto_key_version_path(
        project_id, location_id, key_ring_id, key_id, version_id
    )

    # Call the API.
    destroyed_version = client.destroy_crypto_key_version(
        request={"name": key_version_name}
    )
    print(f"Destroyed key version: {destroyed_version.name}")
    return destroyed_version

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"
# version_id  = "123"

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

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

# Build the key version name.
key_version_name = client.crypto_key_version_path project:            project_id,
                                                  location:           location_id,
                                                  key_ring:           key_ring_id,
                                                  crypto_key:         key_id,
                                                  crypto_key_version: version_id

# Call the API.
destroyed_version = client.destroy_crypto_key_version name: key_version_name
puts "Destroyed key version: #{destroyed_version.name}"

API

这些示例使用 curl 作为 HTTP 客户端来演示如何使用 API。如需详细了解访问权限控制，请参阅访问 Cloud KMS API。

通过调用 CryptoKeyVersions.destroy 方法销毁密钥版本。

curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME/cryptoKeyVersions/KEY_VERSION:destroy" \
    --request "POST" \
    --header "authorization: Bearer TOKEN"

如果您无法销毁密钥版本，则您的组织可能要求在销毁密钥版本之前先停用密钥版本。请尝试先停用密钥版本，然后再销毁。

当您提交销毁请求时，密钥版本的状态将变为已安排销毁。在密钥的配置的已安排销毁时长结束后，密钥版本的状态将变为已销毁，这意味着系统已开始从活跃系统中逻辑删除密钥材料，客户无法恢复密钥材料。密钥材料可能会在 Google 系统中保留长达 45 天（从安排的销毁时间算起）。

如需在密钥版本安排销毁后接收提醒，请参阅将 Cloud Monitoring 与 Cloud KMS 搭配使用。

已销毁的密钥版本不是计费资源。

销毁外部密钥

如需永久移除 Cloud EKM 密钥与外部密钥之间的关联，您可以销毁密钥版本。在“已安排销毁” 期限结束后，密钥将被销毁。密钥版本销毁后，您就无法再加密数据或解密使用 Cloud EKM 密钥版本加密的数据。

在 Cloud KMS 中销毁手动管理的密钥版本不会修改外部密钥管理器中的密钥。我们建议您先销毁密钥或密钥版本。 Google Cloud销毁 Cloud EKM 密钥版本后，您可以销毁外部密钥管理器中的密钥材料。

在 Cloud KMS 中销毁 协同外部密钥版本 __会先销毁密钥版本 Google Cloud，然后向 EKM 发送销毁请求以销毁外部密钥材料。

恢复密钥版本

在密钥版本的状态为“已安排销毁”期间，您可以通过提交恢复请求来恢复密钥版本。

控制台

前往密钥管理 页面，在 Google Cloud 控制台中。

前往 Key Management 页面
点击您将恢复其密钥版本的密钥所在密钥环的名称。
点击您要恢复其密钥版本的密钥。
选中要恢复的密钥版本旁边的复选框。
点击标头中的恢复。
在确认提示中，点击恢复。

gcloud

如需在命令行上使用 Cloud KMS，请先安装或升级到最新版本的 Google Cloud CLI。

gcloud kms keys versions restore key-version \
    --key key \
    --keyring key-ring \
    --location location

将 key-version 替换为要恢复的密钥的版本。将 key 替换为密钥的名称。将 key-ring 替换为密钥所在的密钥环的名称。将 location 替换为密钥环的 Cloud KMS 位置。

如需了解所有标志和可能值，请使用 --help 标志运行命令。

C#

要运行此代码，请先设置 C# 开发环境并安装 Cloud KMS C# SDK。


using Google.Cloud.Kms.V1;

public class RestoreKeyVersionSample
{
    public CryptoKeyVersion RestoreKeyVersion(string projectId = "my-project", string locationId = "us-east1", string keyRingId = "my-key-ring", string keyId = "my-key", string keyVersionId = "123")
    {
        // Create the client.
        KeyManagementServiceClient client = KeyManagementServiceClient.Create();

        // Build the key version name.
        CryptoKeyVersionName cryptoKeyVersionName = new CryptoKeyVersionName(projectId, locationId, keyRingId, keyId, keyVersionId);

        // Call the API.
        CryptoKeyVersion result = client.RestoreCryptoKeyVersion(cryptoKeyVersionName);

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

// restoreKeyVersion attempts to recover a key that has been marked for
// destruction in the past 24h.
func restoreKeyVersion(w io.Writer, name string) error {
	// name := "projects/my-project/locations/us-east1/keyRings/my-key-ring/cryptoKeys/my-key/cryptoKeyVersions/123"

	// 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.RestoreCryptoKeyVersionRequest{
		Name: name,
	}

	// Call the API.
	result, err := client.RestoreCryptoKeyVersion(ctx, req)
	if err != nil {
		return fmt.Errorf("failed to restore key version: %w", err)
	}
	fmt.Fprintf(w, "Restored key version: %s\n", result)
	return nil
}

Java

要运行此代码，请先设置 Java 开发环境并安装 Cloud KMS Java SDK。

import com.google.cloud.kms.v1.CryptoKeyVersion;
import com.google.cloud.kms.v1.CryptoKeyVersionName;
import com.google.cloud.kms.v1.KeyManagementServiceClient;
import java.io.IOException;

public class RestoreKeyVersion {

  public void restoreKeyVersion() 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 keyVersionId = "123";
    restoreKeyVersion(projectId, locationId, keyRingId, keyId, keyVersionId);
  }

  // Schedule destruction of the given key version.
  public void restoreKeyVersion(
      String projectId, String locationId, String keyRingId, String keyId, String keyVersionId)
      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.
      CryptoKeyVersionName keyVersionName =
          CryptoKeyVersionName.of(projectId, locationId, keyRingId, keyId, keyVersionId);

      // Restore the key version.
      CryptoKeyVersion response = client.restoreCryptoKeyVersion(keyVersionName);
      System.out.printf("Restored key version: %s%n", response.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 keyId = 'my-key';
// const versionId = '123';

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

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

// Build the key version name
const versionName = client.cryptoKeyVersionPath(
  projectId,
  locationId,
  keyRingId,
  keyId,
  versionId
);

async function restoreKeyVersion() {
  const [version] = await client.restoreCryptoKeyVersion({
    name: versionName,
  });

  console.log(`Restored key version: ${version.name}`);
  return version;
}

return restoreKeyVersion();

PHP

要运行此代码，请先了解如何在上使用 PHP Google Cloud 并安装 Cloud KMS PHP SDK。

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

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

    // Build the key version name.
    $keyVersionName = $client->cryptoKeyVersionName($projectId, $locationId, $keyRingId, $keyId, $versionId);

    // Call the API.
    $restoreCryptoKeyVersionRequest = (new RestoreCryptoKeyVersionRequest())
        ->setName($keyVersionName);
    $restoredVersion = $client->restoreCryptoKeyVersion($restoreCryptoKeyVersionRequest);
    printf('Restored key version: %s' . PHP_EOL, $restoredVersion->getName());

    return $restoredVersion;
}

Python

要运行此代码，请先设置 Python 开发环境并安装 Cloud KMS Python SDK。

from google.cloud import kms


def restore_key_version(
    project_id: str, location_id: str, key_ring_id: str, key_id: str, version_id: str
) -> kms.CryptoKeyVersion:
    """
    Restore a key version scheduled for destruction.

    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').
        version_id (string): ID of the version to use (e.g. '1').

    Returns:
        CryptoKeyVersion: Restored Cloud KMS key version.

    """

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

    # Build the key version name.
    key_version_name = client.crypto_key_version_path(
        project_id, location_id, key_ring_id, key_id, version_id
    )

    # Call the API.
    restored_version = client.restore_crypto_key_version(
        request={"name": key_version_name}
    )
    print(f"Restored key version: {restored_version.name}")
    return restored_version

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"
# version_id  = "123"

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

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

# Build the key version name.
key_version_name = client.crypto_key_version_path project:            project_id,
                                                  location:           location_id,
                                                  key_ring:           key_ring_id,
                                                  crypto_key:         key_id,
                                                  crypto_key_version: version_id

# Call the API.
restored_version = client.restore_crypto_key_version name: key_version_name
puts "Restored key version: #{restored_version.name}"

API

这些示例使用 curl 作为 HTTP 客户端来演示如何使用 API。如需详细了解访问权限控制，请参阅访问 Cloud KMS API。

通过调用 CryptoKeyVersions.restore 方法恢复密钥版本。

curl "https://cloudkms.googleapis.com/v1/projects/project-id/locations/location-id/keyRings/key-ring-id/cryptoKeys/crypto-key-id/cryptoKeyVersions/version-id:restore" \
    --request "POST" \
    --header "authorization: Bearer token"

恢复请求完成后，密钥版本的状态将变为“已停用”。您必须先启用密钥，然后才能使用该密钥。

必需的 IAM 权限

如需销毁密钥版本，调用者需要拥有密钥、密钥环或项目、文件夹或组织的 cloudkms.cryptoKeyVersions.destroy IAM 权限。

如需恢复密钥版本，调用者需要 cloudkms.cryptoKeyVersions.restore 权限。

这两种权限都授予了 Cloud KMS Admin 角色 (roles/cloudkms.admin)。

删除时间轴

Cloud KMS 承诺在安排的销毁时间后的 45 天内从所有 Google 基础架构中删除客户密钥材料。这包括从活跃系统和数据中心备份中移除数据。其他客户数据受标准 Google Cloud 删除时间轴（180 天）的限制。

销毁和恢复密钥版本 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

准备工作

了解风险

所需的角色

检查密钥版本是否正在使用

销毁密钥版本

控制台

gcloud

C#

Go

Java

Node.js

PHP

Python

Ruby

API

销毁外部密钥

恢复密钥版本

控制台

gcloud

C#

Go

Java

Node.js

PHP

Python

Ruby

API

必需的 IAM 权限

删除时间轴

销毁和恢复密钥版本