迁移外部密钥

本文档介绍了如何在“外部（通过互联网）”(EXTERNAL) 和“外部（通过 VPC）”(EXTERNAL_VPC) 保护级别之间迁移 Cloud EKM 密钥。仅支持使用 gcloud CLI 和 Cloud KMS API 迁移外部密钥。

迁移用例

当密钥的保护级别为 EXTERNAL 或 EXTERNAL_VPC 时，您可以执行以下任一操作：

  • 轮替密钥，创建具有不同 Cloud EKM 保护级别的新密钥版本。例如，您可以轮换 EXTERNAL 保护级别中的密钥，以创建 EXTERNAL_VPC 保护级别中的新密钥版本。
  • 更新密钥版本，以便为同一密钥材料使用其他 Cloud EKM 保护级别。例如，您可以更新保护级别为 EXTERNAL 的密钥版本，使其使用相同的密钥材料和相同的密钥版本资源，但保护级别为 EXTERNAL_VPC。
  • 轮换 EXTERNAL_VPC 密钥或更新 EXTERNAL_VPC 密钥版本以使用与父密钥不同的 EkmConnection。

在两个 Cloud EKM 保护级别之间迁移现有密钥版本，可让您更改外部密钥材料的访问方式，而无需重新配置应用或重新加密数据，并且不会造成停机。 迁移后的密钥使用相同的密钥材料和相同的资源标识符。

将密钥版本从 EXTERNAL 保护级别迁移到 EXTERNAL_VPC 保护级别时，您需要将 EkmConnection 资源与密钥版本相关联，并添加 ekmConnectionKeyPath。将密钥版本从 EXTERNAL_VPC 迁移到 EXTERNAL 保护级别时，您需要添加 externalKeyUri 来替换 EkmConnection 和 ekmConnectionKeyPath。

如果密钥版本具有关联的 EkmConnection，则所有密钥版本操作都会使用该连接，即使父密钥具有不同的 EkmConnection 也是如此。

迁移到通过 VPC 进行的外部路由

从“通过互联网的外部”保护级别迁移到“通过 VPC 的外部”保护级别可提高 Cloud EKM 密钥的可靠性。您可以享受 Virtual Private Cloud (VPC) 网络的优势，包括强大的隔离性和更好的运营支持。

您还可以在不同的 VPC 配置之间进行迁移，例如，从使用 合作伙伴互连的 VPC 升级为使用专用互连的 VPC。

准备工作

在迁移 Cloud EKM 密钥之前，您必须满足以下条件：

  1. 已启用结算功能和 Cloud KMS API 的 Google Cloud 项目。

  2. 如需获得迁移外部密钥所需的权限，请让您的管理员为您授予项目或父级资源的 Cloud KMS Admin (roles/cloudkms.admin) IAM 角色。 如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

    此预定义角色包含迁移外键所需的 cloudkms.cryptoKeys.update 权限。

    您也可以使用自定义角色或其他预定义角色来获取此权限。

  3. 如果您要迁移到“外部”（通过互联网）(EXTERNAL) 保护级别，则必须通过互联网设置 Cloud EKM（如果您尚未这样做）。
  4. 如果您要迁移到“外部通过 VPC”(EXTERNAL_VPC) 保护级别或迁移到新的 VPC 网络，则必须创建 EKM 连接（如果尚未创建）。

创建新的手动管理的外部密钥版本（通过 VPC）

gcloud

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

如需在现有 Cloud EKM 密钥上创建新的“外部密钥通过 VPC”密钥版本，请使用 kms keys versions create 命令以及 --protection-level、--crypto-key-backend 和 --ekm-connection-key-path 标志：

gcloud kms keys versions create \
    --key KEY_NAME \
    --keyring KEY_RING \
    --location LOCATION \
    --protection-level "external-vpc" \
    --crypto-key-backend EKM_CONNECTION_PATH \
    --ekm-connection-key-path EXTERNAL_KEY_PATH

替换以下内容：

  • KEY_NAME：密钥的名称。
  • KEY_RING：包含密钥的密钥环的名称。
  • LOCATION：密钥环的 Cloud KMS 位置。
  • EKM_CONNECTION_PATH：您要用于新密钥版本的 EKM 连接的资源标识符，例如 projects/PROJECT_ID/locations/LOCATION/ekmConnections/EKM_CONNECTION
  • EXTERNAL_KEY_PATH：来自 EKM 连接的新外部密钥版本的路径，例如 v0/path/to/my/key。

如果父键是

如果密钥是对称加密密钥，并且您想将新密钥版本设为主要版本，请添加 --primary 标志。

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

REST

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

如需在现有 Cloud EKM 密钥上创建新的外部密钥版本（通过 VPC），请调用 CryptoKeyVersions.create 方法来创建新的密钥版本。

curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME/cryptoKeyVersions" \
    --request "POST" \
    --header "authorization: Bearer TOKEN" \
    --header "content-type: application/json" \
    --data '{
            "protectionLevel": "EXTERNAL_VPC",
            "externalProtectionLevelOptions": {
              "ekmConnectionKeyPath": "EXTERNAL_KEY_PATH",
              "ekmConnectionBackendOverride": "EKM_CONNECTION_PATH"
              },
            }'
  • PROJECT_ID：包含您要轮换的密钥的项目的标识符。
  • KEY_NAME：密钥的名称。
  • KEY_RING：包含密钥的密钥环的名称。
  • LOCATION：密钥环的 Cloud KMS 位置。
  • EKM_CONNECTION_PATH：您要用于新密钥版本的 EKM 连接的资源标识符，例如 projects/PROJECT_ID/locations/LOCATION/ekmConnections/EKM_CONNECTION
  • EXTERNAL_KEY_PATH：来自 EKM 连接的新外部密钥版本的路径，例如 v0/path/to/my/key。

此命令会创建新的密钥版本，但不会将其设置为主版本。

如需将新密钥版本设置为主密钥版本，请参阅将现有版本设置为主密钥版本。

创建新的外部互联网密钥版本

gcloud

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

如需在现有 Cloud EKM 密钥上创建新的外部互联网密钥版本，请使用 kms keys versions create 命令以及 --protection-level 和 --external-key-uri 标志：

gcloud kms keys versions create \
    --key KEY_NAME \
    --keyring KEY_RING \
    --location LOCATION \
    --protection-level "external" \
    --external-key-uri EXTERNAL_KEY_URI

替换以下内容：

  • KEY_NAME：密钥的名称。
  • KEY_RING：包含密钥的密钥环的名称。
  • LOCATION：密钥环的 Cloud KMS 位置。
  • EXTERNAL_KEY_URI：新外部密钥版本的 URI。

如果密钥是对称加密密钥，并且您想将新密钥版本设为主要版本，请添加 --primary 标志。

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

REST

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

如需在现有的 Cloud EKM 密钥上创建新的外部互联网密钥版本，请调用 CryptoKeyVersions.create 方法来创建新的密钥版本。

curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME/cryptoKeyVersions" \
    --request "POST" \
    --header "authorization: Bearer TOKEN" \
    --header "content-type: application/json" \
    --data '{
            "protectionLevel": "EXTERNAL",
            "externalProtectionLevelOptions": {
              "externalKeyUri": "EXTERNAL_KEY_URI",
              },
            }'
  • PROJECT_ID：包含您要轮换的密钥的项目的标识符。
  • KEY_NAME：密钥的名称。
  • KEY_RING：包含密钥的密钥环的名称。
  • LOCATION：密钥环的 Cloud KMS 位置。
  • EXTERNAL_KEY_URI：新外部密钥版本的 URI。

此命令会创建新的密钥版本，但不会将其设置为主版本。

如需将新密钥版本设置为主密钥版本，请参阅将现有版本设置为主密钥版本。

更新密钥版本以使用“外部通过 VPC”保护模式

gcloud

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

如需将现有 external 密钥版本更新为 external-vpc 保护级别，请将 kms keys versions update 命令与 --protection-level、--crypto-key-backend 和 --ekm-connection-key-path 标志结合使用：

gcloud kms keys versions update KEY_VERSION \
    --key KEY_NAME \
    --keyring KEY_RING \
    --location LOCATION \
    --protection-level "external-vpc" \
    --crypto-key-backend EKM_CONNECTION_PATH \
    --ekm-connection-key-path EXTERNAL_KEY_PATH

替换以下内容：

  • KEY_VERSION：您要迁移的密钥版本的数量，例如 3。
  • KEY_NAME：密钥的名称。
  • KEY_RING：包含密钥的密钥环的名称。
  • LOCATION：密钥环的 Cloud KMS 位置。
  • EKM_CONNECTION_PATH：您要用于密钥版本的 EKM 连接的资源标识符，例如 projects/PROJECT_ID/locations/LOCATION/ekmConnections/EKM_CONNECTION
  • EXTERNAL_KEY_PATH：EKM 连接中现有外部密钥材料的新路径，例如 v0/path/to/my/key。EKM 连接和密钥路径必须指向与当前密钥 URI 相同的密钥材料。

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

REST

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

如需将现有 external 密钥版本更新为 external-vpc 保护级别，请调用 CryptoKeyVersions.patch 方法。

curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME/cryptoKeyVersions/KEY_VERSION?updateMask=protectionLevel,externalProtectionLevelOptions" \
    --request "PATCH" \
    --header "authorization: Bearer TOKEN" \
    --header "content-type: application/json" \
    --data '{
            "protectionLevel": "EXTERNAL_VPC",
            "externalProtectionLevelOptions": {
              "ekmConnectionKeyPath": "EXTERNAL_KEY_PATH",
              "ekmConnectionBackendOverride": "EKM_CONNECTION_PATH"
              },
            }'
  • PROJECT_ID：包含要迁移的密钥的项目的标识符。
  • KEY_NAME：密钥的名称。
  • KEY_RING：包含密钥的密钥环的名称。
  • LOCATION：密钥环的 Cloud KMS 位置。
  • EKM_CONNECTION_PATH：您要用于密钥版本的 EKM 连接的资源标识符，例如 projects/PROJECT_ID/locations/LOCATION/ekmConnections/EKM_CONNECTION
  • EXTERNAL_KEY_PATH：EKM 连接中现有外部密钥材料的新路径，例如 v0/path/to/my/key。EKM 连接和密钥路径必须指向与当前密钥 URI 相同的密钥材料。

更新密钥版本以使用“通过互联网进行外部保护”模式

gcloud

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

如需将现有 external-vpc 密钥版本更新为 external 保护级别，请将 kms keys versions update 命令与 --protection-level 和 --external-key-uri 标志结合使用：

gcloud kms keys versions update KEY_VERSION \
    --key KEY_NAME \
    --keyring KEY_RING \
    --location LOCATION \
    --protection-level "external" \
    --external-key-uri EXTERNAL_KEY_URI

替换以下内容：

  • KEY_VERSION：您要迁移的密钥版本的数量，例如 3。
  • KEY_NAME：密钥的名称。
  • KEY_RING：包含密钥的密钥环的名称。
  • LOCATION：密钥环的 Cloud KMS 位置。
  • EXTERNAL_KEY_URI：EKM 中现有外部密钥材料的新 URI。该 URI 必须指向与当前 EKM 连接和外部密钥相同的密钥材料。

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

REST

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

如需将现有 external-vpc 密钥版本更新为 external 保护级别，请调用 CryptoKeyVersions.patch 方法。

curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME/cryptoKeyVersions/KEY_VERSION?updateMask=protectionLevel,externalProtectionLevelOptions" \
    --request "PATCH" \
    --header "authorization: Bearer TOKEN" \
    --header "content-type: application/json" \
    --data '{
            "protectionLevel": "EXTERNAL",
            "externalProtectionLevelOptions": {
              "externalKeyUri": "EXTERNAL_KEY_URI",
              },
            }'
  • PROJECT_ID：包含要迁移的密钥的项目的标识符。
  • KEY_NAME：密钥的名称。
  • KEY_RING：包含密钥的密钥环的名称。
  • LOCATION：密钥环的 Cloud KMS 位置。
  • EXTERNAL_KEY_URI：EKM 中现有外部密钥材料的新 URI。该 URI 必须指向与当前 EKM 连接和外部密钥相同的密钥材料。