为 Secret Manager 启用客户管理的加密密钥

本主题讨论了 Secret Manager 中客户管理的加密密钥 (CMEK)。

概览

Secret Manager 提供用于存储、管理和访问应用中的敏感数据的工具。

默认情况下，存储在 Secret Manager 中的 Secret 使用 Google 默认加密方法进行加密。使用 Google 默认加密时，Secret 载荷会在写入永久性存储空间之前由 Google 管理的密钥进行加密，无需任何配置。

您可以通过提供密钥加密密钥来自定义 Secret Manager 对您的资源使用的加密方式。密钥加密密钥不会直接加密您的数据，而是对 Google 生成的用于加密数据的密钥进行加密。您可以直接创建 CMEK 密钥，也可以使用 Cloud KMS 自动密钥（预览版）代表您创建这些密钥。如需了解详情，请参阅 Autokey 概览。

如需详细了解 Google Cloud 中的加密选项，请参阅默认静态加密。如需了解有关 CMEK 的具体信息（包括其优势和限制），请参阅客户管理的加密密钥。

CMEK 在 Secret Manager 中的工作原理

在将密文版本写入特定位置的永久性存储空间之前，Secret Manager 会使用唯一的数据加密密钥 (DEK) 对数据进行加密。然后，此 DEK 使用副本专用密钥（称为密钥加密密钥 KEK，由 Secret Manager 服务拥有）进行加密。

将 CMEK 用于 Secret Manager 时，KEK 称为 CMEK 密钥，是您在 Cloud KMS 中管理的对称密钥。CMEK 密钥必须与其加密的 Secret 版本副本位于同一 Google Cloud 位置。您还可以在 CMEK 政策中使用 Cloud EKM 密钥进行加密和解密。

本指南介绍了如何配置 Secret Manager 以使用 CMEK。如需大致了解 CMEK（包括其启用时间和原因），请参阅 Cloud Key Management Service 文档。

限制

CMEK 仅在 Secret Manager v1 API 和 gCloud 中可用。

准备工作

您可以选择将所有资源存储在同一项目中，或将密文和密钥存储在不同的项目中。阅读 Cloud KMS 职责分离，以更好地了解此决策。

完成以下前提条件，以设置 Secret Manager 和 Cloud KMS：

  • Secret Manager：

    • 创建或使用现有项目来保存您的 Secret Manager 资源。
    • 如有必要，请完成 Secret Manager 快速入门的配置 Secret Manager 部分中的步骤。

  • Cloud KMS：

    • 创建或使用现有项目来保留您的 Cloud KMS 资源。
    • 如有必要，请启用 Cloud KMS API。

将以下变量设置为 Secret Manager 和 Cloud KMS 项目的 ID。

This is an editable variable. Set it to your Secret Manager project ID and the
value will be used in all commands on this page.
SM_PROJECT_ID

This is an editable variable. Set it to your Cloud KMS project ID and the value
will be used in all commands on this page.
KMS_PROJECT_ID

向 Google Cloud 进行身份验证：

gcloud

如需在命令行中使用 Secret Manager，请先安装或升级到 378.0.0 或更高版本的 Google Cloud CLI。在 Compute Engine 或 GKE 上，您必须使用 cloud-platform 范围进行身份验证。

gcloud auth login

手动或自动密钥创建

您可以手动创建 Cloud KMS 密钥，也可以使用 Cloud KMS Autokey（预览版）。Autokey 通过自动执行预配和分配来简化 Cloud KMS 密钥的创建和管理。借助 Autokey，您无需提前预配密钥环、密钥和服务账号。而是会在 Secret Manager 资源创建过程中按需生成。如需了解详情，请参阅 Autokey 概览。如需为 Secret Manager 启用 Autokey，请参阅启用 Autokey。如需将 Autokey 与 Secret 搭配使用，请参阅将 Autokey 与 Secret Manager 资源搭配使用。

本页面中的说明适用于手动创建和分配 Cloud KMS 密钥。

创建服务代理身份

您需要为每个需要 CMEK 的项目创建一个服务代理身份。

如需使用 Google Cloud CLI 创建服务身份，请运行以下命令：

gcloud

如需在命令行中使用 Secret Manager，请先安装或升级到 378.0.0 或更高版本的 Google Cloud CLI。在 Compute Engine 或 GKE 上，您必须使用 cloud-platform 范围进行身份验证。

gcloud beta services identity create \
    --service "secretmanager.googleapis.com" \
    --project "SM_PROJECT_ID"

这将按以下格式返回服务身份名称：

service-PROJECT_NUMBER@gcp-sa-secretmanager.iam.gserviceaccount.com

保存服务身份名称：

The following variable is editable. Click on it to update the value, and it will
be reflected throughout this documentation page.

SM_SERVICE_IDENTITY

您要向此服务身份授予对用于加密和解密密文的 CMEK Cloud KMS 密钥的访问权限。

具有自动复制功能的 CMEK

本部分涉及通过自动复制政策配置的密文。

对于使用自动复制政策的 Secret，您的 CMEK 密钥必须位于 global Cloud KMS 多区域中。如果您使用的是 Cloud EKM 密钥，则无法将密钥配置为使用自动复制功能，因为 Cloud EKM 密钥在 global 区域不可用。如需详细了解如何使用 Cloud EKM 密钥，请参阅将 Cloud EKM 密钥添加到 CMEK 政策。

在 global Cloud KMS 区域中创建对称 Cloud KMS 密钥，或使用现有密钥。本示例会创建一个名为 secret-manager-cmek 的新密钥环，然后在其上创建名为 my-cmek-key 的新密钥。

gcloud

如需在命令行中使用 Secret Manager，请先安装或升级到 378.0.0 或更高版本的 Google Cloud CLI。在 Compute Engine 或 GKE 上，您必须使用 cloud-platform 范围进行身份验证。

gcloud kms keyrings create "secret-manager-cmek" \
    --project "KMS_PROJECT_ID" \
    --location "global"

gcloud kms keys create "my-cmek-key" \
    --project "KMS_PROJECT_ID" \
    --location "global" \
    --keyring "secret-manager-cmek" \
    --purpose "encryption"

向服务身份授予 Secret Manager 访问权限，以便使用 CMEK 密钥进行加密和解密。此命令会向服务身份授予 my-cmek-key Cloud KMS 密钥上的 Cloud KMS 加密/解密角色 (roles/cloudkms.cryptoKeyEncrypterDecrypter)。

gcloud

如需在命令行中使用 Secret Manager，请先安装或升级到 378.0.0 或更高版本的 Google Cloud CLI。在 Compute Engine 或 GKE 上，您必须使用 cloud-platform 范围进行身份验证。

gcloud kms keys add-iam-policy-binding "my-cmek-key" \
    --project "KMS_PROJECT_ID" \
    --location "global" \
    --keyring "secret-manager-cmek" \
    --member "serviceAccount:SM_SERVICE_IDENTITY" \
    --role "roles/cloudkms.cryptoKeyEncrypterDecrypter"

通过自动复制创建密文。CMEK 密钥的资源名称以密文上的元数据形式存储。

gcloud

如需在命令行中使用 Secret Manager，请先安装或升级到 378.0.0 或更高版本的 Google Cloud CLI。在 Compute Engine 或 GKE 上，您必须使用 cloud-platform 范围进行身份验证。

gcloud secrets create "SECRET_ID" \
    --replication-policy "automatic" \
    --kms-key-name "projects/KMS_PROJECT_ID/locations/global/keyRings/secret-manager-cmek/cryptoKeys/my-cmek-key" \
    --project "SM_PROJECT_ID"

API

这些示例使用 curl 来使用 API 演示。 您可以使用 gcloud auth print-access-token 生成访问令牌。在 Compute Engine 或 GKE 上，您必须使用 cloud-platform 范围进行身份验证。

将 replication.automatic.customerManagedEncryption.kmsKeyName 的值设置为 CMEK 密钥的资源名称。

curl "https://secretmanager.googleapis.com/v1/projects/${SM_PROJECT_ID}/secrets?secretId=SECRET_ID" \
    --request "POST" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer ACCESS_TOKEN" \
    --data-binary @- <<EOF
{
  "replication":{
    "automatic":{
      "customerManagedEncryption":{
        "kmsKeyName": "projects/KMS_PROJECT_ID/locations/global/keyRings/secret-manager-cmek/cryptoKeys/my-cmek-key"
      }
    }
  }
}
EOF

现在，每次在该密文中创建密文版本时，只要该服务身份有权访问 CMEK 密钥，系统就会使用密钥，在写入密文之前自动使用密钥的载荷进行加密。如果服务身份失去访问权限，或者密钥不可用，则尝试创建新密文版本或访问现有密文版本会返回错误。

添加新的密文版本。请注意，您未指定 Cloud KMS 密钥的资源名称；从密文的元数据中读取此密钥。

gcloud

如需在命令行中使用 Secret Manager，请先安装或升级到 378.0.0 或更高版本的 Google Cloud CLI。在 Compute Engine 或 GKE 上，您必须使用 cloud-platform 范围进行身份验证。

echo -n "SECRET_DATA" | gcloud secrets versions add "SECRET_ID" \
    --project "SM_PROJECT_ID" \
    --data-file -

即使调用者无法直接访问 CMEK 密钥，系统也会创建密文版本。Secret Manager（而不是调用者）的服务身份负责在读取或写入密文时进行加密和解密。

同样，您无需直接访问 CMEK 密钥即可访问密文。服务身份会访问密钥，并代表您加密或解密密文。

访问您刚刚创建的密文版本：

gcloud

如需在命令行中使用 Secret Manager，请先安装或升级到 378.0.0 或更高版本的 Google Cloud CLI。在 Compute Engine 或 GKE 上，您必须使用 cloud-platform 范围进行身份验证。

gcloud secrets versions access "latest" \
    --project "SM_PROJECT_ID" \
    --secret "SECRET_ID"

更新 CMEK 配置

在 global Cloud KMS 多区域中创建新的对称 KMS 密钥。

gcloud

如需在命令行中使用 Secret Manager，请先安装或升级到 378.0.0 或更高版本的 Google Cloud CLI。在 Compute Engine 或 GKE 上，您必须使用 cloud-platform 范围进行身份验证。

gcloud kms keys create "my-other-key" \
    --project "KMS_PROJECT_ID" \
    --location "global" \
    --keyring "secret-manager-cmek" \
    --purpose "encryption"

向服务身份授予 Secret Manager 访问权限，以便使用新的 CMEK 密钥进行加密和解密。此命令会向服务身份授予 my-other-key Cloud KMS 密钥上的 Cloud KMS 加密/解密角色 (roles/cloudkms.cryptoKeyEncrypterDecrypter)。

gcloud

如需在命令行中使用 Secret Manager，请先安装或升级到 378.0.0 或更高版本的 Google Cloud CLI。在 Compute Engine 或 GKE 上，您必须使用 cloud-platform 范围进行身份验证。

gcloud kms keys add-iam-policy-binding "my-other-key" \
    --project "KMS_PROJECT_ID" \
    --location "global" \
    --keyring "secret-manager-cmek" \
    --member "serviceAccount:SM_SERVICE_IDENTITY" \
    --role "roles/cloudkms.cryptoKeyEncrypterDecrypter"

使用新的 Cloud KMS 密钥资源名称更新密文副本，以修改密文的 CMEK 配置。

gcloud

如需在命令行中使用 Secret Manager，请先安装或升级到 378.0.0 或更高版本的 Google Cloud CLI。在 Compute Engine 或 GKE 上，您必须使用 cloud-platform 范围进行身份验证。

gcloud secrets replication update "SECRET_ID" \
    --set-kms-key "projects/KMS_PROJECT_ID/locations/global/keyRings/secret-manager-cmek/cryptoKeys/my-other-key" \
    --project "SM_PROJECT_ID"

API

这些示例使用 curl 来使用 API 演示。 您可以使用 gcloud auth print-access-token 生成访问令牌。在 Compute Engine 或 GKE 上，您必须使用 cloud-platform 范围进行身份验证。

curl "https://secretmanager.googleapis.com/v1/projects/${SM_PROJECT_ID}/secrets/SECRET_ID?updateMask=replication" \
    --request "PATCH" \
    --header "Authorization: Bearer ACCESS_TOKEN" \
    --header "Content-Type: application/json" \
    --data-binary @- <<EOF
{
  "replication": {
    "automatic":{
      "customerManagedEncryption":{
        "kmsKeyName": "projects/KMS_PROJECT_ID/locations/global/keyRings/secret-manager-cmek/cryptoKeys/my-other-key"
      }
    }
  }
}
EOF

采用用户管理的复制政策配置的 CMEK

本部分介绍了使用用户管理的复制政策配置的密文。通过用户管理的复制政策，您可以控制存储 Secret 的 Google Cloud 位置。Secret 始终可以从每个 Google Cloud 位置访问。

采用用户管理的复制政策的 Secret 必须使用与 Secret 版本的存储位置完全一致的 Cloud KMS 密钥。本指南中的示例将 Secret 存储在两个单独的位置：us-east1、us-central1。访问密文的请求将传送到其中一个位置。

在这两个区域中，请创建一个密钥环和一个 Cloud KMS 密钥以进行加密，或使用现有密钥。此示例会创建一个名为 "secret-manager-cmek" 的新密钥环，然后在每个区域中创建一个名为 "my-cmek-key" 的密钥。

gcloud

如需在命令行中使用 Secret Manager，请先安装或升级到 378.0.0 或更高版本的 Google Cloud CLI。在 Compute Engine 或 GKE 上，您必须使用 cloud-platform 范围进行身份验证。

gcloud kms keyrings create "secret-manager-cmek" \
    --project "KMS_PROJECT_ID" \
    --location "us-east1"

gcloud kms keys create "my-cmek-key" \
    --project "KMS_PROJECT_ID" \
    --location "us-east1" \
    --keyring "secret-manager-cmek" \
    --purpose "encryption"

gcloud kms keyrings create "secret-manager-cmek" \
    --project "KMS_PROJECT_ID" \
    --location "us-central1"

gcloud kms keys create "my-cmek-key" \
    --project "KMS_PROJECT_ID" \
    --location "us-central1" \
    --keyring "secret-manager-cmek" \
    --purpose "encryption"

通过为每个 CMEK 密钥单独授予或为项目中的所有密钥授予 Cloud KMS 加密/解密角色 (roles/cloudkms.cryptoKeyEncrypterDecrypter)，为服务身份授予 Secret Manager 访问权限，以使用 CMEK 密钥加密和解密。

gcloud

如需在命令行中使用 Secret Manager，请先安装或升级到 378.0.0 或更高版本的 Google Cloud CLI。在 Compute Engine 或 GKE 上，您必须使用 cloud-platform 范围进行身份验证。

gcloud kms keys add-iam-policy-binding "my-cmek-key" \
    --project "KMS_PROJECT_ID" \
    --location "us-east1" \
    --keyring "secret-manager-cmek" \
    --member "serviceAccount:SM_SERVICE_IDENTITY" \
    --role "roles/cloudkms.cryptoKeyEncrypterDecrypter"

gcloud kms keys add-iam-policy-binding "my-cmek-key" \
    --project "KMS_PROJECT_ID" \
    --location "us-central1" \
    --keyring "secret-manager-cmek" \
    --member "serviceAccount:SM_SERVICE_IDENTITY" \
    --role "roles/cloudkms.cryptoKeyEncrypterDecrypter"

使用用户管理的复制政策创建启用了 CMEK 的密文。CMEK 密钥的资源名称以密文上的元数据形式存储。

gcloud

如需在命令行中使用 Secret Manager，请先安装或升级到 378.0.0 或更高版本的 Google Cloud CLI。在 Compute Engine 或 GKE 上，您必须使用 cloud-platform 范围进行身份验证。

cat <<EOF > ./replication-policy.json
{
  "userManaged":{
    "replicas":[
      {
        "location":"us-east1",
        "customerManagedEncryption":{
          "kmsKeyName":"projects/KMS_PROJECT_ID/locations/us-east1/keyRings/secret-manager-cmek/cryptoKeys/my-cmek-key"
        }
      },
      {
        "location":"us-central1",
        "customerManagedEncryption":{
          "kmsKeyName":"projects/KMS_PROJECT_ID/locations/us-central1/keyRings/secret-manager-cmek/cryptoKeys/my-cmek-key"
        }
      }
    ]
  }
}
EOF

gcloud secrets create "my-ummr-secret" \
    --replication-policy-file ./replication-policy.json \
    --project "SM_PROJECT_ID"

API

这些示例使用 curl 来使用 API 演示。 您可以使用 gcloud auth print-access-token 生成访问令牌。在 Compute Engine 或 GKE 上，您必须使用 cloud-platform 范围进行身份验证。

将 replication.userManaged.replicas.customerManagedEncryption.kmsKeyName 的值设置为 CMEK 密钥的资源名称。

curl "https://secretmanager.googleapis.com/v1/projects/SM_PROJECT_ID/secrets?secretId=my-ummr-secret" \
--request "POST" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer ACCESS_TOKEN" \
--data-binary @- <<EOF
{
  "replication":{
    "userManaged":{
      "replicas":[
        {
          "location":"us-east1",
          "customerManagedEncryption":{
            "kmsKeyName":"projects/KMS_PROJECT_ID/locations/us-east1/keyRings/secret-manager-cmek/cryptoKeys/my-cmek-key"
          }
        },
        {
          "location":"us-central1",
          "customerManagedEncryption":{
            "kmsKeyName":"projects/KMS_PROJECT_ID/locations/us-central1/keyRings/secret-manager-cmek/cryptoKeys/my-cmek-key"
          }
        }
      ]
    }
  }
}
EOF

现在，每次在该密文中创建密文版本时，只要该服务身份有权访问 CMEK 密钥，系统就会使用密钥，在写入密文之前自动使用密钥的载荷进行加密。如果服务身份失去访问权限，或者密钥不可用，则尝试创建新密文版本或访问现有密文版本会返回错误。

添加新的密文版本。请注意，您未指定 Cloud KMS 密钥的资源名称；从密文的元数据中读取此密钥。

gcloud

如需在命令行中使用 Secret Manager，请先安装或升级到 378.0.0 或更高版本的 Google Cloud CLI。在 Compute Engine 或 GKE 上，您必须使用 cloud-platform 范围进行身份验证。

echo -n "SECRET_DATA" | gcloud secrets versions add "my-ummr-secret" \
    --project "SM_PROJECT_ID" \
    --data-file -

即使调用者无法直接访问 CMEK 密钥，系统也会创建密文版本。Secret Manager（而不是调用者）的服务身份负责在读取或写入密文时进行加密和解密。

同样，您无需直接访问 CMEK 密钥即可访问密文。服务身份会访问密钥，并代表您加密或解密密文。

访问您刚刚创建的密文版本。

gcloud

如需在命令行中使用 Secret Manager，请先安装或升级到 378.0.0 或更高版本的 Google Cloud CLI。在 Compute Engine 或 GKE 上，您必须使用 cloud-platform 范围进行身份验证。

gcloud secrets versions access "latest" \
    --project "SM_PROJECT_ID" \
    --secret "my-ummr-secret"

更新 CMEK 配置

在密钥所属的相同区域中创建两个新的对称 KMS 密钥。

gcloud

如需在命令行中使用 Secret Manager，请先安装或升级到 378.0.0 或更高版本的 Google Cloud CLI。在 Compute Engine 或 GKE 上，您必须使用 cloud-platform 范围进行身份验证。

gcloud kms keys create "my-other-key" \
    --project "KMS_PROJECT_ID" \
    --location "us-east1" \
    --keyring "secret-manager-cmek" \
    --purpose "encryption"

gcloud kms keys create "my-other-key" \
    --project "KMS_PROJECT_ID" \
    --location "us-central1" \
    --keyring "secret-manager-cmek" \
    --purpose "encryption"

向服务身份授予 Secret Manager 访问权限，以便使用新的 CMEK 密钥进行加密和解密。此命令会向服务身份授予 my-other-key Cloud KMS 密钥上的 Cloud KMS 加密/解密角色 (roles/cloudkms.cryptoKeyEncrypterDecrypter)。

gcloud

如需在命令行中使用 Secret Manager，请先安装或升级到 378.0.0 或更高版本的 Google Cloud CLI。在 Compute Engine 或 GKE 上，您必须使用 cloud-platform 范围进行身份验证。

gcloud kms keys add-iam-policy-binding "my-other-key" \
    --project "KMS_PROJECT_ID" \
    --location "us-east1" \
    --keyring "secret-manager-cmek" \
    --member "serviceAccount:SM_SERVICE_IDENTITY" \
    --role "roles/cloudkms.cryptoKeyEncrypterDecrypter"

gcloud kms keys add-iam-policy-binding "my-other-key" \
    --project "KMS_PROJECT_ID" \
    --location "us-central1" \
    --keyring "secret-manager-cmek" \
    --member "serviceAccount:SM_SERVICE_IDENTITY" \
    --role "roles/cloudkms.cryptoKeyEncrypterDecrypter"

使用新的 Cloud KMS 密钥资源名称更新密文副本，以修改密文的 CMEK 配置。

gcloud

如需在命令行中使用 Secret Manager，请先安装或升级到 378.0.0 或更高版本的 Google Cloud CLI。在 Compute Engine 或 GKE 上，您必须使用 cloud-platform 范围进行身份验证。

gcloud secrets replication update "my-ummr-secret" \
    --set-kms-key "projects/KMS_PROJECT_ID/locations/us-east1/keyRings/secret-manager-cmek/cryptoKeys/my-other-key" \
    --location us-east1 \
    --project "SM_PROJECT_ID"

gcloud secrets replication update "my-ummr-secret" \
    --set-kms-key "projects/KMS_PROJECT_ID/locations/us-central1/keyRings/secret-manager-cmek/cryptoKeys/my-other-key" \
    --location us-central1 \
    --project "SM_PROJECT_ID"

要同时更新密文中的多个密钥，您可以通过文件获取和设置复制政策。

gcloud

如需在命令行中使用 Secret Manager，请先安装或升级到 378.0.0 或更高版本的 Google Cloud CLI。在 Compute Engine 或 GKE 上，您必须使用 cloud-platform 范围进行身份验证。

gcloud secrets replication get "my-ummr-secret" \
    --project "SM_PROJECT_ID" \
    --format=json > ./replication-policy.json

更新该文件，在您的首选编辑器中反映所需的 CMEK 配置。然后设置新政策：

gcloud secrets replication set "my-ummr-secret" \
    --replication-policy-file ./replication-policy.json \
    --project "SM_PROJECT_ID"

API

这些示例使用 curl 来使用 API 演示。 您可以使用 gcloud auth print-access-token 生成访问令牌。在 Compute Engine 或 GKE 上，您必须使用 cloud-platform 范围进行身份验证。

curl "https://secretmanager.googleapis.com/v1/projects/${SM_PROJECT_ID}/secrets/my-ummr-secret?updateMask=replication" \
    --request "PATCH" \
    --header "Authorization: Bearer ACCESS_TOKEN" \
    --header "Content-Type: application/json" \
    --data-binary @- <<EOF
{
  "replication":{
    "userManaged":{
      "replicas":[
        {
          "location":"us-east1",
          "customerManagedEncryption":{
            "kmsKeyName":"projects/KMS_PROJECT_ID/locations/us-east1/keyRings/secret-manager-cmek/cryptoKeys/my-other-key"
          }
        },
        {
          "location":"us-central1",
          "customerManagedEncryption":{
            "kmsKeyName":"projects/KMS_PROJECT_ID/locations/us-central1/keyRings/secret-manager-cmek/cryptoKeys/my-other-key"
          }
        }]
      }
    }
  }
EOF

查看 Secret 版本 CMEK 配置

如需检查密文版本的元数据（包括密文版本是否启用 CMEK 和 CMEK 密钥版本的资源名称），请查看其元数据。

gcloud

如需在命令行中使用 Secret Manager，请先安装或升级到 378.0.0 或更高版本的 Google Cloud CLI。在 Compute Engine 或 GKE 上，您必须使用 cloud-platform 范围进行身份验证。

gcloud secrets versions describe "latest" \
    --secret "SECRET_ID" \
    --project "SM_PROJECT_ID"

API

这些示例使用 curl 来使用 API 演示。 您可以使用 gcloud auth print-access-token 生成访问令牌。在 Compute Engine 或 GKE 上，您必须使用 cloud-platform 范围进行身份验证。

curl "https://secretmanager.googleapis.com/v1/projects/SM_PROJECT_ID/secrets/SECRET_ID/versions/latest" \
    --request "GET" \
    --header "Authorization: Bearer ACCESS_TOKEN" \
    --header "Content-Type: application/json"

这将返回用于加密密文版本的密钥版本的完整 Cloud KMS 资源名称。

{
  "name": "projects/PROJECT_NUMBER/secrets/SECRET_ID/versions/1",
  "createTime": "2021-07-...",
  "state": "ENABLED",
  "replicationStatus": {
    "automatic": {
      "customerManagedEncryption": {
        "kmsKeyVersionName": "projects/KMS_PROJECT_ID/locations/global/keyRings/secret-manager-cmek/cryptoKeys/my-cmek-key/cryptoKeyVersions/1"
      }
    }
  }
}

将 Cloud EKM 密钥添加到 CMEK 政策

本部分介绍如何将 Cloud EKM 密钥添加到 CMEK 政策。以下步骤可让 Cloud EKM 密钥用于加密或解密 Secret。

由于 Cloud EKM 目前不支持 global 多区域，因此 Cloud EKM 密钥只能用于为用户管理的复制配置的 Secret。

在 us-central1 Cloud KMS 区域（或除 global 以外的任何区域）中创建一个对称密钥。此示例会创建一个名为 secret-manager-cmek-ekm 的新密钥环，然后针对该密钥环创建一个名为 my-ekm-key 的新密钥。

gcloud

如需在命令行中使用 Secret Manager，请先安装或升级到 378.0.0 或更高版本的 Google Cloud CLI。在 Compute Engine 或 GKE 上，您必须使用 cloud-platform 范围进行身份验证。

创建新的密钥环：

gcloud kms keyrings create "secret-manager-cmek-ekm" \
  --project "KMS_PROJECT_ID" \
  --location "us-central1"

在该密钥环中创建密钥：

gcloud kms keys create "my-ekm-key" \
  --keyring "secret-manager-cmek-ekm" \
  --location "us-central1" \
  --purpose "encryption" \
  --protection-level "external" \
  --skip-initial-version-creation \
  --default-algorithm "external-symmetric-encryption"

接下来，使用该密钥的外部 URI 创建新版 my-ekm-key。如需详细了解 Cloud EKM 密钥的外部 URI，请参阅创建外部密钥。

gcloud

如需在命令行中使用 Secret Manager，请先安装或升级到 378.0.0 或更高版本的 Google Cloud CLI。在 Compute Engine 或 GKE 上，您必须使用 cloud-platform 范围进行身份验证。

gcloud kms keys versions create \
  --key "my-ekm-key" \
  --keyring "secret-manager-cmek-ekm" \
  --location "us-central1" \
  --external-key-uri EXTERNAL_KEY_URI \
  --primary

向服务身份授予 Secret Manager 使用外部密钥进行加密和解密的权限。此命令将 my-ekm-key 上的 Cloud KMS Encrypter / Decrypter 角色 (roles/cloudkms.cryptoKeyEncrypterDecrypter) 授予服务身份。

gcloud

如需在命令行中使用 Secret Manager，请先安装或升级到 378.0.0 或更高版本的 Google Cloud CLI。在 Compute Engine 或 GKE 上，您必须使用 cloud-platform 范围进行身份验证。

gcloud kms keys add-iam-policy-binding "my-ekm-key" \
  --project "KMS_PROJECT_ID" \
  --location "us-central1" \
  --keyring "secret-manager-cmek-ekm" \
  --member "serviceAccount:SM_SERVICE_IDENTITY" \
  --role "roles/cloudkms.cryptoKeyEncrypterDecrypter"

创建使用 Cloud EKM 密钥且启用了 CMEK 的密钥。

gcloud

如需在命令行中使用 Secret Manager，请先安装或升级到 378.0.0 或更高版本的 Google Cloud CLI。在 Compute Engine 或 GKE 上，您必须使用 cloud-platform 范围进行身份验证。

cat <<EOF > ./replication-policy.json
{
  "userManaged":{
    "replicas":[
      {
        "location":"us-central1",
        "customerManagedEncryption":{
          "kmsKeyName":"projects/KMS_PROJECT_ID/locations/us-central1/keyRings/secret-manager-cmek-ekm/cryptoKeys/my-ekm-key"
        }
      }
    ]
  }
}
EOF

gcloud secrets create "my-ekm-secret" \
    --replication-policy-file ./replication-policy.json \
    --project "SM_PROJECT_ID"

现在，每次在 my-ekm-secret 中创建密文版本时，只要该服务身份有权访问该密钥，系统就会使用 Cloud EKM 密钥，在写入密文之前自动使用密钥的载荷进行加密。如果服务身份失去访问权限，或者密钥不可用，则尝试创建新密文版本或访问现有密文版本会返回错误。

添加新的密文版本。请注意，密钥的资源名称是从 Secret 的元数据中读取的。

gcloud

如需在命令行中使用 Secret Manager，请先安装或升级到 378.0.0 或更高版本的 Google Cloud CLI。在 Compute Engine 或 GKE 上，您必须使用 cloud-platform 范围进行身份验证。

echo -n "SECRET_DATA" | gcloud secrets versions add "my-ekm-secret" \
    --project "SM_PROJECT_ID" \
    --data-file -

即使调用者无法直接访问密钥，系统也会创建密文版本。Secret Manager（而不是调用者）的服务身份负责在读取或写入密文时进行加密和解密。

访问您刚刚创建的密文版本。 这是服务身份访问密钥并代表您加密或解密密文的位置。

gcloud

如需在命令行中使用 Secret Manager，请先安装或升级到 378.0.0 或更高版本的 Google Cloud CLI。在 Compute Engine 或 GKE 上，您必须使用 cloud-platform 范围进行身份验证。

gcloud secrets versions access "latest" \
  --project "SM_PROJECT_ID" \
  --secret "my-ekm-secret"

停用 CMEK

通过更新复制政策，从密文中移除 CMEK 配置。

gcloud

如需在命令行中使用 Secret Manager，请先安装或升级到 378.0.0 或更高版本的 Google Cloud CLI。在 Compute Engine 或 GKE 上，您必须使用 cloud-platform 范围进行身份验证。

gcloud secrets replication update "SECRET_ID" --remove-cmek \
    --project "SM_PROJECT_ID"

API

这些示例使用 curl 来使用 API 演示。 您可以使用 gcloud auth print-access-token 生成访问令牌。在 Compute Engine 或 GKE 上，您必须使用 cloud-platform 范围进行身份验证。

curl "https://secretmanager.googleapis.com/v1/projects/${SM_PROJECT_ID}/secrets/SECRET_ID?updateMask=replication" \
    --request "PATCH" \
    --header "Authorization: Bearer ACCESS_TOKEN" \
    --header "Content-Type: application/json" \
    --data-binary @- <<EOF
{
  "replication":{
    "automatic":{}
  }
}
EOF

后续步骤

  • 详细了解 CMEK。