Como usar chaves de criptografia gerenciadas pelo cliente

Neste tópico, mostramos como proteger imagens de contêiner implantadas nos serviços do Cloud Run usando chaves de criptografia gerenciadas pelo cliente (CMEK) do Cloud KMS. É possível usar esse recurso para proteger contêineres importados pelo Cloud Run com uma chave CMEK em repouso.

É necessário levar em conta as seguintes informações:

Os metadados de arquivos, como o caminho do arquivo, não são criptografados.
Os metadados do serviço do Cloud Run, como nome ou variáveis de ambiente, não são criptografados usando a chave fornecida, mas uma chave gerenciada pelo Google.
No ambiente de execução, o conteúdo da memória e do arquivo não é criptografado.
Se uma chave CMEK estiver desativada, as novas instâncias de revisões atuais do Cloud Run que a usam não serão iniciadas.
Se uma chave CMEK estiver desativada, a implantação de uma nova revisão do Cloud Run falhará, a menos que uma nova chave válida seja usada.

Como as chaves CMEK são controladas por você e não pelo Google, ninguém, inclusive o Google, pode acessar os dados protegidos por essas chaves de criptografia quando elas são desativadas ou destruídas.

O uso de CMEKs gera registros de auditoria. Consulte Noções básicas sobre registros de auditoria e mensagens de erro para mais detalhes.

Cotas do Cloud KMS e o Cloud Run

É possível definir a CMEK como um dos níveis de proteção disponíveis para indicar como as operações criptográficas são realizadas. Quando você usa CMEK no Cloud Run, seus projetos podem consumir cotas de solicitações criptográficas do Cloud KMS. Por exemplo, repositórios criptografados por CMEK podem consumir essas cotas em cada upload ou download.

As operações de criptografia e descriptografia com chaves CMEK afetam as cotas do Cloud KMS destas maneiras:

Para chaves CMEK de software geradas no Cloud KMS, nenhuma cota do Cloud KMS é consumida.
Para chaves CMEK de hardware, às vezes chamadas de chaves do Cloud HSM, as operações de criptografia e descriptografia são descontadas das cotas do Cloud HSM no projeto que contém a chave.
Para chaves CMEK externas, às vezes chamadas de chaves do Cloud EKM, as operações de criptografia e descriptografia são descontadas das cotas do Cloud EKM no projeto que contém a chave.

Para mais informações, consulte Cotas do Cloud KMS.

Comportamento de escalonamento automático afetado por CMEK

O escalonamento automático esperado do serviço do Cloud Run pode ser afetado quando você usa chaves de criptografia gerenciadas pelo cliente. Por exemplo, a latência para iniciar novas instâncias pode aumentar devido a atrasos no contato com sistemas externos de gerenciamento de chaves durante operações de chave.

A tabela a seguir mostra as possíveis mudanças de comportamento devido ao uso de chaves CMEK:

Operação relacionada a CMEK	Comportamento de escalonamento automático
Chave desativada/destruída/revogada	Novas instâncias não serão iniciadas.
Não é possível entrar em contato com o gerenciador de chaves externo	Se a nova solicitação de chave for repetida, nenhuma instância será desligada durante as novas tentativas e nenhuma nova instância será iniciada. O escalonamento horizontal pode parecer mais lento do que o esperado. Se não for possível repetir a solicitação de chave, nenhuma nova instância será iniciada e as instâncias em execução serão encerradas após um período de espera.
Cota de KMS excedida	Se essa cota for excedida, os erros `RESOURCE_EXHAUSTED` serão registrados e as novas instâncias não serão iniciadas. É possível solicitar uma cota adicional para corrigir o problema.

Antes de começar

Ative a API Cloud Run Admin

Permitir que o Cloud Run acesse uma chave

Para usar a CMEK para o Cloud Run, siga estas etapas:

Configure o Artifact Registry para usar CMEK.
Use o Guia de início rápido do Docker do Artifact Registry como referência para criar um repositório do Docker e envie uma imagem para ele.
Use uma chave simétrica do Cloud KMS atual ou crie uma nova chave simétrica.
Para permitir o acesso do Cloud Run à chave, conceda ao agente de serviço do Cloud Run o papel de criptografador/descriptografador de CryptoKey do Cloud KMS:
Console
1. Acesse a página "Chaves criptográficas".
2. Clique no keyring da sua chave para abrir a página da lista de chaves.
3. Selecione a chave e, na guia "Permissões" à direita, clique em Adicionar principal.
4. No campo Novos principais, copie o e-mail do agente de serviço do Cloud Run. Ele tem o seguinte sufixo:
  
  PROJECT_NUMBER@serverless-robot-prod.iam.gserviceaccount.com.
5. No menu suspenso Selecionar um papel, escolha Criptografador/descriptografador de CryptoKey do Cloud KMS.
6. Clique em Salvar.
Linha de comando
Use o seguinte comando gcloud kms:
```
gcloud kms keys add-iam-policy-binding KEY_NAME \
--keyring=KEYRING \
--location=LOCATION) \
--member serviceAccount:PROJECT_NUMBER@serverless-robot-prod.iam.gserviceaccount.com \
--role='roles/cloudkms.cryptoKeyEncrypterDecrypter'
```
Substituir
- KEY_NAME pelo nome da chave.
- KEYRING pelo nome do keyring;
- LOCATION pelo nome da sua região;
- PROJECT_NUMBER pelo número do projeto em que você pretende implantar o serviço do Cloud Run.
Você precisa de permissão para administrar os recursos do Cloud KMS no projeto do Google Cloud para conceder o papel roles/cloudkms.cryptoKeyEncrypterDecrypter do IAM. Somente membros do IAM com papéis de Proprietário (roles/owner) ou Administrador (roles/cloudkms.admin) do Cloud KMS podem conceder ou revogar acesso aos recursos do Cloud KMS.

Configurar a CMEK para um serviço do Cloud Run

Qualquer mudança na configuração leva à criação de uma nova revisão. As próximas revisões também recebem automaticamente essa configuração, a menos que você faça atualizações explícitas para alterá-la.

Console

No console do Google Cloud, acesse o Cloud Run:

Acesse o Cloud Run
Clique em Criar serviço se estiver configurando um novo serviço em que fará uma implantação. Se você estiver configurando um serviço atual, clique nele e em Editar e implantar nova revisão.
Se você estiver configurando um novo serviço, preencha a página inicial de configurações do serviço conforme preferir e clique em Contêineres, volumes, rede, segurança para expandir a página de configurações do serviço.
Clique na guia Segurança.
- Em Criptografia:
  1. Selecione Chave de criptografia gerenciada pelo cliente (CMEK).
  2. No menu Selecionar uma chave gerenciada pelo cliente, escolha uma das seguintes opções:
  3. No menu de ações Revogação de chave, escolha uma das seguintes opções:
Clique em Criar ou Implantar.

Linha de comando

Para definir uma chave em um serviço, use um dos seguintes comandos:

gcloud run deploy SERVICE \
--image IMAGE_URL \
--key KEY \
--post-key-revocation-action-type KEY_REVOCATION_ACTION
--encryption-key-shutdown-hours SHUTDOWN_HOURS

gcloud run services update SERVICE --key KEY
--post-key-revocation-action-type KEY_REVOCATION_ACTION
--encryption-key-shutdown-hours SHUTDOWN_HOURS

Substituir

SERVICE pelo nome do serviço;
IMAGE_URL por uma referência à imagem de contêiner. Por exemplo, us-docker.pkg.dev/cloudrun/container/hello:latest. Se você usa o Artifact Registry, o repositório REPO_NAME já precisará ter sido criado. O URL tem o formato LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
KEY pelo nome totalmente qualificado da chave no seguinte formato: projects/PROJECT_NAME/locations/LOCATION/keyRings/KEYRING_NAME/cryptoKeys/KEY_NAME.
KEY_REVOCATION_ACTION por shut-down ou prevent-new, dependendo das suas preferências de revogação de chave.
SHUTDOWN_HOURS pelo número de horas de atraso antes de encerrar o serviço após a revogação.

YAML

Se você estiver criando um novo serviço, pule esta etapa. Se você estiver atualizando um serviço existente, faça o download da configuração YAML correspondente:
```
gcloud run services describe SERVICE --format export > service.yaml
```
Atualize as seguintes anotações de CMEK para os valores desejados:
```
apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: SERVICE
spec:
  template:
    metadata:
      annotations:
        run.googleapis.com/encryption-key: projects/PROJECT_NAME/locations/LOCATION/keyRings/KEYRING_NAME/cryptoKeys/KEY_NAME
        run.googleapis.com/post-key-revocation-action-type: KEY_REVOCATION_ACTION
        run.googleapis.com/encryption-key-shutdown-hours: SHUTDOWN_HOURS
      name: REVISION
```
Substituir
- SERVICE pelo nome do serviço do Cloud Run;
- PROJECT_NAME pelo nome do projeto em que a chave foi criada.
- LOCATION pelo local em que a chave foi criada. Ele precisa corresponder ao local do serviço do Cloud Run.
- KEYRING_NAME pelo nome do keyring.
- KEY_NAME pelo nome da chave.
- KEY_REVOCATION_ACTION por shut-down ou prevent-new, dependendo das suas preferências de revogação de chave.
- SHUTDOWN_HOURS pelo número de horas de atraso antes de encerrar o serviço após a revogação.
- REVISION por um novo nome de revisão ou excluir essa opção (quando possível). Se você fornecer um novo nome de revisão, ele precisará atender aos seguintes critérios:
  - Começa com SERVICE-
  - Contém apenas letras minúsculas, números e -
  - Não termina com um -
  - Não excede 63 caracteres
Substitua o serviço pela nova configuração usando o seguinte comando:
```
gcloud run services replace service.yaml
```

Exibir as configurações de segurança

Para ver as configurações de simultaneidade atuais do serviço do Cloud Run:

Console

No console do Google Cloud, acesse o Cloud Run:

Acesse o Cloud Run
Clique no serviço de seu interesse para abrir a página Detalhes do serviço.
Clique na guia Revisões.
No painel de detalhes à direita, a configuração de segurança está listada na guia Segurança.

Linha de comando

Use o comando a seguir:
```
gcloud run services describe SERVICE
```
Localize a configuração de segurança na configuração retornada.

Testar a revogação de CMEK

Execute o seguinte comando para confirmar se o serviço está acessível:
```
curl SERVICE_URL
```
Substitua SERVICE_URL pelo URL do serviço. Ele aparece na IU do console após a implantação: o URL do contêiner é exibido ao lado do texto URL:.
Desativar a versão da chave
Aguarde o número de SHUTDOWN_HOURS especificado. Se você não tiver especificado, reative sua chave e edite ou reimplante o serviço com o valor definido como o mínimo de uma hora.
Depois de aguardar o período de SHUTDOWN_HOURS, execute novamente o comando abaixo e confirme se o serviço não está mais acessível:

curl SERVICE_URL

Noções básicas sobre registros de auditoria e mensagens de erro

Se você for responsável pelo monitoramento dos registros de auditoria, uma das tarefas pode ser verificar operações CMEK no serviço do Cloud Run. Nesse caso, você precisa entender os registros de auditoria relacionados.

Se você for responsável por resolver e corrigir erros de ambiente de execução do serviço do Cloud Run, talvez seja necessário solucionar os problemas relacionados à CMEK registrados durante a operação do serviço do Cloud Run.

As seções a seguir fornecem as informações necessárias para as tarefas acima.

Registros de auditoria

Os registros de auditoria do KMS fornecem uma trilha de auditoria para cada operação realizada com uma chave. Para os serviços do Cloud Run com CMEK ativado, o Cloud Run adiciona o contexto do autor da chamada específico do Cloud Run que detalha por que a chave do cliente foi acessada pelo sistema. A tabela a seguir lista os contextos que podem ser vistos nos registros de auditoria:

Motivo do acesso à chave	Descrição
`Decrypting CMEK-encrypted layer during container clone start.`	Registrado sempre que uma nova instância é iniciada.
`Encrypting a newly created data-encryption-key w/ the customer-managed-encryption-key.`	Registrado durante a implantação de um serviço ativado para CMEK, em que a chave CMEK é encapsulada por uma chave KMS.
`Decrypting an existing encrypted data-encryption-key, under the same customer-managed-encryption-key, to be used to encrypt container contents.`	Registrado quando uma nova instância é iniciada e requer a descriptografia da imagem.
`Performing an encrypt operation on dummy data to check the customer-managed-encryption-key status and access.`	Registrado sempre que há uma verificação de validação na chave, que é feita periodicamente.
`Performing an decrypt operation on dummy data to check the customer-managed-encryption-key status and access.`	Registrado sempre que há uma verificação de validação na chave, que é feita periodicamente.

Para detalhes sobre o formato e o conteúdo do registro de auditoria, consulte a página Registro de auditoria do KMS.

Mensagens de erro

As mensagens de erro fornecidas por um gerenciador de chaves externo são transmitidas diretamente para os registros do Cloud Run do seu serviço.

A tabela a seguir lista as mensagens de erro relacionadas à CMEK, além de descrições e possíveis soluções.

Message	Descrição
`User's service account does not have CMEK decrypter permission. Service account: %s`	Solução: permitir que o serviço acesse a chave
`User's KMS operation quota has been exceeded. CMEK key: %s`	O serviço ativado para CMEK excedeu as cotas do KMS. Solução: solicite mais cota de KMS
`User's CMEK key has been disabled. CMEK key: %s`	A chave CMEK foi revogada. Solução: altere a chave CMEK do serviço e reimplante o serviço.
`User's CMEK key has been destroyed. CMEK key: %s`	A chave CMEK foi excluída. Solução: altere a chave CMEK do serviço e reimplante o serviço.
`User's CMEK key has been scheduled for deletion. CMEK Key: %s`	A chave CMEK foi programada para exclusão. Solução: altere a chave CMEK do serviço e reimplante o serviço.

A seguir

Saiba mais sobre permissões e papéis no Cloud KMS.
Criar uma chave.
Registros de auditoria