此页面由 Cloud Translation API 翻译。

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

默认情况下，Secret Manager 会对以静态方式存储的客户内容进行加密。Secret Manager 会为您处理加密，您无需执行任何其他操作。此选项称为 Google 默认加密。

如果您想要控制加密密钥，则可以将 Cloud KMS 中客户管理的加密密钥 (CMEK) 与集成 CMEK 的服务（包括 Secret Manager）结合使用。使用 Cloud KMS 密钥时，您可以控制其保护级别、位置、轮替时间表、使用和访问权限以及加密边界。此外，您还可使用 Cloud KMS 跟踪密钥使用情况、查看审核日志并控制密钥生命周期。这样您就可以在 Cloud KMS 中控制和管理用于保护您数据的对称密钥加密密钥 (KEK)，而不是由 Google 拥有和管理这些密钥。

使用 CMEK 设置资源后，访问 Secret Manager 资源的体验与使用 Google 默认加密功能类似。如需详细了解加密选项，请参阅客户管理的加密密钥 (CMEK)。

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

将 CMEK 与 Cloud KMS Autokey 结合使用

您可以手动创建 CMEK 来保护 Secret Manager 资源，也可以使用 Cloud KMS Autokey。借助 Autokey，在 Secret Manager 中创建资源时，系统会按需生成密钥环和密钥。系统会创建使用密钥执行加密和解密操作的服务代理（如果它们尚不存在），并授予所需的 Identity and Access Management (IAM) 角色。如需了解详情，请参阅 Autokey 概览。

只有在使用 Terraform 或 REST API 创建资源时，Secret Manager 才与 Cloud KMS Autokey 兼容。

如需了解如何使用手动创建的 CMEK 来保护 Secret Manager 资源，请参阅本页中的使用自动复制功能的 CMEK 和使用用户管理的复制功能的 CMEK。

如需了解如何使用 Cloud KMS Autokey 创建的 CMEK 来保护 Secret Manager 资源，请参阅将 Autokey 与 Secret Manager 资源结合使用。

CMEK 在 Secret Manager 中的工作原理

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

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

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

限制

CMEK 仅在 Secret Manager v1 API 和 Google Cloud CLI 中可用。

准备工作

您可以选择将所有资源存储在同一项目中，或将密文和密钥存储在不同的项目中。阅读 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，请先安装或升级到 Google Cloud CLI 378.0.0 或更高版本。在 Compute Engine 或 GKE 上，您必须使用 cloud-platform 范围进行身份验证。

gcloud auth login

创建服务代理身份

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

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

gcloud

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

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

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

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

gcloud

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

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

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

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

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

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

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

gcloud

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

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

更新 CMEK 配置

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

gcloud

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

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

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

本部分介绍了使用用户管理的复制政策配置的密文。借助用户管理的复制政策，您可以控制存储密文的 Google Cloud 位置。密文可以随时从每个 Google Cloud 位置进行访问。

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

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

gcloud

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

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

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

将 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

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

gcloud

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

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

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

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

gcloud

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

更新 CMEK 配置

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

gcloud

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"

gcloud

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

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

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

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

API

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

创建新的密钥环：

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

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 加密 / 解密角色 (roles/cloudkms.cryptoKeyEncrypterDecrypter)。

gcloud

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"

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

gcloud

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 密钥，在写入密文之前自动使用密钥的载荷进行加密。如果服务身份失去访问权限，或者密钥不可用，则尝试创建新密文版本或访问现有密文版本会返回错误。

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

gcloud

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

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

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

gcloud

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

停用 CMEK

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

gcloud

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

API

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。