遷移外部金鑰

本文說明如何在「外部透過網際網路」(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 保護層級之間遷移現有金鑰版本，可讓您變更外部金鑰素材的存取方式，不必重新設定應用程式或重新加密資料，而且不會停機。遷移的金鑰使用相同的金鑰素材和資源 ID。

將金鑰版本從 EXTERNAL 防護等級遷移至 EXTERNAL_VPC 防護等級時，您會將 EkmConnection 資源與金鑰版本建立關聯，並新增 ekmConnectionKeyPath。從 EXTERNAL_VPC 遷移至 EXTERNAL 保護等級時，您會新增 externalKeyUri 來取代 EkmConnection 和 ekmConnectionKeyPath。

如果金鑰版本有相關聯的 EkmConnection，所有金鑰版本作業都會使用該連線，即使父項金鑰有不同的 EkmConnection 也是如此。

遷移至透過虛擬私有雲連線的外部金鑰

從「外部透過網際網路」保護層級遷移至「外部透過 VPC」保護層級，可提高 Cloud EKM 金鑰的可靠性。您可享有虛擬私有雲 (VPC) 網路的優點，包括強大的隔離功能和更完善的作業支援。

您也可以在不同的虛擬私有雲設定之間遷移，例如從使用Partner Interconnect的虛擬私有雲升級為使用Dedicated Interconnect的虛擬私有雲。

事前準備

您必須具備下列條件，才能遷移 Cloud EKM 金鑰：

  1. 已啟用計費功能和 Cloud KMS API 的 Google Cloud 專案。

  2. 如要取得遷移外部金鑰所需的權限，請要求管理員在專案或上層資源中，授予您「Cloud KMS 管理員 」(roles/cloudkms.admin) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

    這個預先定義的角色具備 cloudkms.cryptoKeys.update 權限，可遷移外部金鑰。

    您或許還可透過自訂角色或其他預先定義的角色取得這項權限。

  3. 如果您要遷移至透過網際網路的外部 (EXTERNAL) 保護層級，則必須透過網際網路設定 Cloud EKM (如果尚未設定)。
  4. 如果您要遷移至「透過 VPC 的外部」EXTERNAL_VPC防護等級，或是遷移至新的 VPC 網路，則必須建立 EKM 連線 (如果尚未建立)。

建立新的手動管理外部金鑰版本 (透過虛擬私有雲)

gcloud

如要在指令列上使用 Cloud KMS，請先安裝或升級至最新版 Google Cloud CLI。

如要在現有的 Cloud EKM 金鑰上建立新的外部虛擬私有雲金鑰版本，請使用 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 連線資源 ID，例如 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 金鑰上建立新的外部虛擬私有雲金鑰版本，請呼叫 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：包含您要輪替金鑰的專案 ID。
  • KEY_NAME：金鑰名稱。
  • KEY_RING：金鑰所屬金鑰環的名稱。
  • LOCATION：金鑰環的 Cloud KMS 位置。
  • EKM_CONNECTION_PATH：要用於新金鑰版本的 EKM 連線資源 ID，例如 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：包含您要輪替金鑰的專案 ID。
  • KEY_NAME：金鑰名稱。
  • KEY_RING：金鑰所屬金鑰環的名稱。
  • LOCATION：金鑰環的 Cloud KMS 位置。
  • EXTERNAL_KEY_URI：新外部金鑰版本的 URI。

這項指令會建立新的金鑰版本，但不會將其設為主要版本。

如要將新金鑰版本設為主要版本，請參閱「將現有版本設定為主要金鑰版本」。

更新金鑰版本，以使用透過虛擬私有雲連線的外部保護模式

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 連線資源 ID，例如 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：包含要遷移金鑰的專案 ID。
  • KEY_NAME：金鑰名稱。
  • KEY_RING：金鑰所屬金鑰環的名稱。
  • LOCATION：金鑰環的 Cloud KMS 位置。
  • EKM_CONNECTION_PATH：要用於金鑰版本的 EKM 連線資源 ID，例如 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：包含要遷移金鑰的專案 ID。
  • KEY_NAME：金鑰名稱。
  • KEY_RING：金鑰所屬金鑰環的名稱。
  • LOCATION：金鑰環的 Cloud KMS 位置。
  • EXTERNAL_KEY_URI：EKM 中現有外部金鑰素材的新 URI。URI 必須指向與目前 EKM 連線和外部金鑰相同的金鑰內容。