Ativar as chaves de criptografia gerenciadas pelo cliente para o Secret Manager

Este tópico aborda o suporte para Chaves de criptografia gerenciadas pelo cliente (CMEK, na sigla em inglês) no Secret Manager.

Informações gerais

O Secret Manager oferece ferramentas para armazenar, gerenciar e acessar dados confidenciais nos aplicativos.

Por padrão, os secrets armazenados no Secret Manager são criptografados com a criptografia padrão do Google. Com a criptografia padrão do Google, os payloads do secret são criptografados por chaves gerenciadas pelo Google antes de serem gravados no armazenamento permanente, sem necessidade de configuração. A criptografia padrão do Google é a melhor escolha para muitas organizações.

Para organizações que querem ter mais controle, o suporte de CMEK para o Secret Manager permite configurar a chave do Cloud KMS que protege os dados em repouso no Secret Manager.

Como o CMEK funciona no Secret Manager

Antes de gravar uma versão do secret no armazenamento permanente de um local específico, o Secret Manager criptografa os dados com uma chave exclusiva de criptografia de dados (DEK, na sigla em inglês). Essa DEK é criptografada com uma chave específica da réplica, chamada de chave de criptografia de chaves (KEK, na sigla em inglês), que pertence ao serviço do Secret Manager.

Quando você usa a CMEK para o Secret Manager, a KEK é chamada de chave de CMEK e é uma chave simétrica que pode ser gerenciada no Cloud KMS. A chave CMEK precisa estar no mesmo local do Google Cloud que a réplica da versão do secret criptografada. Também é possível usar uma chave do Cloud EKM na política de CMEK para criptografia e descriptografia.

Este guia explica como configurar o Secret Manager para usar a CMEK. Para mais informações gerais sobre a CMEK, incluindo como quando e por que ativar, consulte a documentação do Cloud Key Management Service.

Limitações

A CMEK está disponível apenas na API v1 do Secret Manager e na gCloud.

Antes de começar

É possível optar por armazenar todos os recursos no mesmo projeto ou armazenar secrets e chaves em projetos separados. Leia a Separação de tarefas do Cloud KMS para entender melhor essa decisão.

Conclua os seguintes pré-requisitos para configurar o Secret Manager e o Cloud KMS:

Secret Manager:
- Crie ou use um projeto atual para armazenar os recursos do Secret Manager.
- Se necessário, conclua as etapas na seção Como configurar o Secret Manager do guia de início rápido do Secret Manager.
Cloud KMS:
- Crie ou use um projeto atual para armazenar os recursos do Cloud KMS.
- Se necessário, ative a API Cloud KMS.

Defina as variáveis a seguir como os IDs dos projetos do Secret Manager e do Cloud KMS.

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

Faça a autenticação no Google Cloud:

gcloud

Para usar o Secret Manager na linha de comando, primeiro instale ou faça upgrade para a versão 378.0.0 ou mais recente da Google Cloud CLI. No Compute Engine ou no GKE, você precisa fazer a autenticação com o escopo do cloud-platform.

gcloud auth login

Como criar uma identidade de agente de serviço

É necessário criar uma identidade de agente de serviço para cada projeto que exige chaves de criptografia gerenciadas pelo cliente.

Para criar uma identidade de serviço com a Google Cloud CLI, execute o seguinte comando:

gcloud

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

que retornará um nome de identidade de serviço no seguinte formato:

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

Salve o nome da identidade do serviço:

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

SM_SERVICE_IDENTITY

Você concederá a essa identidade de serviço acesso às chaves CMEK do Cloud KMS usadas para criptografar e descriptografar seus secrets.

CMEK com replicação automática

Nesta seção, abordamos os secrets configurados por meio de uma política de replicação automática.

Para secrets que usam a política de replicação automática, sua chave CMEK precisa estar localizada na multirregião global do Cloud KMS. Se você estiver usando uma chave do Cloud EKM, não será possível configurar o secret para usar a replicação automática, porque as chaves do Cloud EKM não estão disponíveis na região global. Para saber mais sobre como usar chaves do Cloud EKM, consulte Adicionar uma chave do Cloud EKM a uma política de CMEK.

Crie uma chave simétrica do Cloud KMS na região global do Cloud KMS ou use uma chave atual. Este exemplo cria um novo keyring com o nome secret-manager-cmek e, em seguida, uma nova chave com o nome 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"

Conceda à identidade de serviço o acesso do Secret Manager para criptografar e descriptografar usando a chave de CMEK. Esse comando concede o papel criptografador/descriptografador do Cloud KMS (roles/cloudkms.cryptoKeyEncrypterDecrypter) à chave my-cmek-key do Cloud KMS à identidade do serviço.

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"

Crie um secret com replicação automática. O nome do recurso da chave CMEK é armazenado como metadados no secret.

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

Esses exemplos usam curl para demonstrar o uso da API. É possível gerar tokens de acesso com o gcloud auth print-access-token. No Compute Engine ou no GKE, você precisa fazer a autenticação com o escopo do cloud-platform.

Defina o valor de replication.automatic.customerManagedEncryption.kmsKeyName como o nome do recurso para a chave de 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

Agora, sempre que uma versão do secret é criada nesse secret, o payload dessa versão é automaticamente criptografado usando a chave antes de ser gravado no armazenamento permanente, desde que a identidade do serviço tenha acesso à chave CMEK. Se a identidade do serviço perder o acesso ou se a chave ficar indisponível, uma tentativa de criar uma nova versão do secret ou acessar uma existente retornará um erro.

Adicione uma nova versão do secret. Você não especifica o nome do recurso da chave do Cloud KMS. Ele é lido a partir dos metadados do secret.

gcloud

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

A versão do secret é criada, mesmo que o autor da chamada não tenha acesso direto para usar a chave CMEK. A identidade do serviço do Secret Manager, e não do autor da chamada, é responsável por criptografar e descriptografar os secrets ao lê-los ou gravar.

Da mesma forma, você não precisa de acesso direto à chave CMEK para acessar o secret. A identidade do serviço acessa a chave e criptografa ou descriptografa a chave em seu nome.

Acesse a versão do secret que você acabou de criar:

gcloud

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

Atualizar configuração de CMEK

Crie chaves KMS simétricas na multirregião global do Cloud KMS.

gcloud

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

Conceda à identidade de serviço o acesso do Secret Manager para criptografar e descriptografar usando a nova chave de CMEK. Esse comando concede o papel criptografador / descriptografador do Cloud KMS (roles/cloudkms.cryptoKeyEncrypterDecrypter) à chave my-other-key do Cloud KMS à identidade do serviço.

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"

Modifique a configuração de CMEK em um secret atualizando a replicação nele com os novos nomes de recursos de chaves do Cloud KMS.

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 com replicação gerenciada pelo usuário

Nesta seção, abordamos os secrets configurados com uma política de replicação gerenciada pelo usuário. Com uma política de replicação gerenciada pelo usuário, você controla o local do Google Cloud em que o secret é armazenado. Os secrets estão sempre acessíveis de todos os locais do Google Cloud.

Os secrets com uma política de replicação gerenciada pelo usuário precisam usar chaves do Cloud KMS que mapeiam exatamente para os locais em que as versões do secret são armazenadas. Os exemplos neste guia armazenam um secret em dois locais separados: us-east1 e us-central1. As solicitações para acessar o secret são encaminhadas para um desses locais.

Em cada uma das duas regiões, crie um keyring e uma chave do Cloud KMS para fins de criptografia ou use uma chave atual. Neste exemplo, criamos um novo keyring chamado "secret-manager-cmek" e, em seguida, uma chave com o nome "my-cmek-key" em cada região.

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"

Conceda à identidade de serviço ao Secret Manager permissão para criptografar e descriptografar usando a chave CMEK, concedendo o papel criptografador/descriptografador do Cloud KMS (roles/cloudkms.cryptoKeyEncrypterDecrypter) para cada uma das chaves individualmente ou para todas as chaves do projeto.

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"

Crie um secret ativado para CMEK com replicação gerenciada pelo usuário. O nome do recurso da chave CMEK é armazenado como metadados no secret.

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

Defina o valor de replication.userManaged.replicas.customerManagedEncryption.kmsKeyName como os nomes dos recursos das chaves 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

Adicione uma nova versão do secret. Você não especifica o nome do recurso da chave do Cloud KMS. Ele é lido a partir dos metadados do secret.

gcloud

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

Da mesma forma, você não precisa de acesso direto à chave CMEK para acessar o secret. A identidade do serviço acessa a chave e criptografa ou descriptografa a chave em seu nome.

Acesse a versão do secret que você acabou de criar.

gcloud

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

Atualizar configuração de CMEK

Crie duas novas chaves KMS simétricas nas mesmas regiões do secret.

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"

Conceda à identidade de serviço o acesso do Secret Manager para criptografar e descriptografar usando as novas chaves de CMEK. Esse comando concede o papel criptografador / descriptografador do Cloud KMS (roles/cloudkms.cryptoKeyEncrypterDecrypter) às chaves my-other-key do Cloud KMS à identidade do serviço.

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"

Modifique a configuração de CMEK em um secret atualizando a replicação nele com os novos nomes de recursos de chaves do Cloud KMS.

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"

Para atualizar várias chaves simultaneamente em um secret, é possível receber e definir a política de replicação por meio de um arquivo.

gcloud

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

Atualize o arquivo para refletir a configuração de CMEK pretendida no editor de sua preferência. Em seguida, defina a nova política:

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

Mostrar a configuração de CMEK da versão do secret

Para inspecionar os metadados de uma versão do secret, incluindo se a versão do secret está ativada para CMEKs e o nome do recurso da versão da chave de CMEK, visualize os metadados dela.

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"

Isso retorna o nome completo do recurso do Cloud KMS da versão da chave usada para criptografar a versão do secret.

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

Adicionar uma chave do Cloud EKM a uma política de CMEK

Nesta seção, explicamos como adicionar uma chave do Cloud EKM a uma política de CMEK. Essas etapas permitem que uma chave do Cloud EKM seja usada para criptografar ou descriptografar secrets.

Como o Cloud EKM atualmente não é compatível com a multirregião global, as chaves do Cloud EKM só podem ser usadas com secrets configurados para replicação gerenciada pelo usuário.

Crie uma chave simétrica na região us-central1 do Cloud KMS (ou em qualquer região, exceto global). Neste exemplo, criamos um novo keyring chamado secret-manager-cmek-ekm e outra chave chamada my-ekm-key no keyring.

gcloud

Crie um keyring:

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

Crie uma chave nesse keyring:

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"

Em seguida, crie uma nova versão da my-ekm-key usando o URI externo da chave. Para mais informações sobre URIs externos para chaves do Cloud EKM, consulte Criar uma chave externa.

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

Conceda à identidade de serviço o acesso do Secret Manager para criptografar e descriptografar usando a chave externa. Esse comando concede o papel criptografador / descriptografador do Cloud KMS (roles/cloudkms.cryptoKeyEncrypterDecrypter) em my-ekm-key à identidade do serviço.

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"

Crie um secret ativado para CMEK que use uma chave do Cloud EKM.

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"

Agora, sempre que uma versão do secret é criada em my-ekm-secret, o payload da versão é automaticamente criptografado usando a chave do Cloud EKM antes de ser gravado no armazenamento permanente, desde que a identidade do serviço tenha acesso à chave. Se a identidade do serviço perder o acesso ou se a chave ficar indisponível, uma tentativa de criar uma nova versão do secret ou acessar uma existente retornará um erro.

Adicione uma nova versão do secret. O nome do recurso da chave é lido nos metadados do secret.

gcloud

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

A versão do secret é criada, mesmo que o autor da chamada não tenha acesso direto para usar a chave. A identidade de serviço do Secret Manager, em vez do autor da chamada, é responsável por criptografar e descriptografar os secrets ao lê-los ou gravá-los.

Acesse a versão do secret que você acabou de criar. É aqui que a identidade do serviço acessa a chave e criptografa ou descriptografa o secret em seu nome.

gcloud

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

Desativar a CMEK

Atualize a política de replicação para remover a configuração de CMEK de um secret.

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

A seguir

Saiba mais sobre o CMEK.