Como usar recursos criptografados

Nesta página explicamos como usar recursos criptografados em suas solicitações de versão. Use recursos criptografados, como arquivos ou variáveis, para passar informações confidenciais, como tokens de autorização, nas etapas da criação.

Criptografe e descriptografe recursos usando CryptoKeys do Cloud Key Management Service (Cloud KMS), com que é possível gerenciar de maneira flexível e fácil o acesso e a rotação de chaves de criptografia. As CryptoKeys são armazenadas em KeyRings, que são agrupamentos de CryptoKeys para fins organizacionais.

Acesse o Guia de início rápido do Cloud KMS para se familiarizar com o Cloud KMS e ativar a API Cloud KMS.

Como criar KeyRing e CryptoKey do Cloud KMS

Crie KeyRings e CryptoKeys usando os comandos gcloud kms keyrings create e gcloud kms keys create.

Para criar um KeyRing, execute o seguinte comando no shell ou na janela do terminal:

gcloud kms keyrings create [KEYRING-NAME] \
  --location=global

Para criar um CryptoKey:

gcloud kms keys create [KEY-NAME] \
  --location=global \
  --keyring=[KEYRING-NAME] \
  --purpose=encryption

em que:

  • [KEYRING-NAME] é o nome do KeyRing a ser criado
  • [KEY-NAME] é o nome da CryptoKey a ser criada

Conceder permissão para que a conta de serviço do Cloud Build acesse a CryptoKey

Para descriptografar seu recurso durante a versão, é necessário conceder à conta de serviço do Cloud Build permissão para acessar sua CryptoKey. Se for necessário apenas descriptografar o arquivo, você só precisa conceder permissão de descriptografia.

Para conceder permissão:

Console

  1. Acesse o menu do IAM no Console do GCP.
  2. Copie o endereço de e-mail da conta de serviço do Cloud Build, que contém @cloudbuild.gserviceaccount.com.
  3. Acesse o menu de chaves de criptografia no Console do GCP.
  4. Selecione seu KeyRing na lista.
  5. Clique em Mostrar painel de informações para abrir o painel de informações.
  6. Clique em Permissão.
  7. Clique em Adicionar membro e preencha o campo Novos membros com o endereço de e-mail da conta de serviço.
  8. Em Selecionar um papel, escolha Descriptografador do Cloud KMS CryptoKey.
  9. Clique em Salvar.

gcloud

Execute o seguinte comando no shell ou na janela do terminal:

gcloud kms keys add-iam-policy-binding \
    [KEY-NAME] --location=global --keyring=[KEYRING-NAME] \
    --member=serviceAccount:[PROJECT_NUMBER]@cloudbuild.gserviceaccount.com \
    --role=roles/cloudkms.cryptoKeyDecrypter

Para saber mais sobre esse comando, consulte a documentação gcloud kms keys.

Se você não souber o endereço de e-mail da conta de serviço do Cloud Build, acesse o menu do IAM no Console do Google Cloud Platform. O endereço de e-mail da conta de serviço contém @cloudbuild.gserviceaccount.com.

Para saber mais sobre como conceder acesso a chaves, consulte Como usar o IAM com o Cloud KMS na documentação do Cloud KMS.

Como criptografar um arquivo usando uma CryptoKey

Para criptografar um arquivo, execute o seguinte comando no shell ou na janela do terminal:

gcloud kms encrypt \
  --plaintext-file=secrets.json \
  --ciphertext-file=secrets.json.enc \
  --location=global \
  --keyring=[KEYRING-NAME] \
  --key=[KEY-NAME]

Isso produz um arquivo criptografado chamado secrets.json.enc, que contém o conteúdo de secrets.json.

Como armazenar o arquivo criptografado

Depois de criptografar seu arquivo, armazene-o no mesmo local que o código-fonte, como em um Cloud Source Repository ou em um repositório conectado do GitHub ou Bitbucket.

Por exemplo, para adicionar e confirmar o arquivo criptografado no seu repositório Git:

git add secrets.json.enc
git commit -am "Add encrypted secrets.json.enc"
git push

Para evitar a confirmação do arquivo de texto simples secrets.json em seu repositório, adicione o nome do arquivo ao arquivo gitignore do seu repositório.

echo "secrets.json" >> .gitignore
git commit -am "Add secrets.json to .gitignore"
git push

Como descriptografar o arquivo durante sua versão

Agora que seu arquivo está criptografado com uma chave de criptografia que pode ser acessada pela conta de serviço do Builder, adicione uma etapa da criação para descriptografar o conteúdo do arquivo criptografado.

Em sua solicitação de versão, antes de qualquer etapa de criação que interaja com o arquivo secrets.json descriptografado, adicione uma etapa da criação que chame o criador gcloud para descriptografar secrets.json.enc usando a chave de criptografia. Essa etapa da criação é semelhante aos comandos usados para criptografar o arquivo.

steps:
- name: gcr.io/cloud-builders/gcloud
  args:
  - kms
  - decrypt
  - --ciphertext-file=secrets.json.enc
  - --plaintext-file=secrets.json
  - --location=global
  - --keyring=[KEYRING-NAME]
  - --key=[KEY-NAME]
# more steps here

Após a conclusão dessa etapa, as etapas subsequentes podem usar o arquivo secrets.json descriptografado no diretório do espaço de trabalho.

Por exemplo, use os secrets neste arquivo para buscar dependências externas ou para incluir tokens de secret em imagens de contêiner do Docker que você criar.

Como criptografar uma variável de ambiente usando CryptoKeys

Para criptografar uma variável de ambiente, execute o seguinte comando no shell ou na janela do terminal:

echo -n $MY_SECRET | gcloud kms encrypt \
  --plaintext-file=- \  # - reads from stdin
  --ciphertext-file=- \  # - writes to stdout
  --location=global \
  --keyring=[KEYRING-NAME] \
  --key=[KEY-NAME] | base64

Esse comando criptografa o valor da variável de ambiente $MY_SECRET usando a CryptoKey. O valor criptografado é uma string codificada em base64 para que você inclua facilmente o valor em sua solicitação da versão.

Como usar a variável criptografada em solicitações de versão

Em sua solicitação da versão, inclua um campo secrets, que especifica o valor criptografado, e a CryptoKey a ser usada para descriptografá-lo:

secrets:
- kmsKeyName: projects/[PROJECT-ID]/locations/global/keyRings/[KEYRING-NAME]/cryptoKeys/[KEY-NAME]
  secretEnv:
    MY_SECRET: <base64-encoded encrypted secret>

Nas etapas da criação, especifique se o valor descriptografado estará disponível como uma variável de ambiente:

steps:
- name: 'my-builder-image'
  args: ['my', 'args']
  env: ['FOO=foo', 'BAR=bar']
  secretEnv: ['MY_SECRET']

Exemplo de solicitação de versão usando uma variável criptografada

A solicitação da versão de exemplo a seguir envia uma imagem do Docker para o Dockerhub usando uma senha do Dockerhub criptografada:

steps:

# Pull a public image from Dockerhub.
- name: 'gcr.io/cloud-builders/docker'
  args: ['pull', 'ubuntu']

# Retag the image into a user's repository.
- name: 'gcr.io/cloud-builders/docker'
  args: ['tag', 'ubuntu', '[MY-USER]/myubuntu']

# Login to provide credentials for the push.
# PASSWORD is decrypted before this step runs.
# Note: You need a shell to resolve environment variables with $$
- name: 'gcr.io/cloud-builders/docker'
  entrypoint: 'bash'
  args: ['-c', 'docker login --username=[MY-USER] --password=$$PASSWORD']
  secretEnv: ['PASSWORD']

# Push the image to Dockerhub.
- name: 'gcr.io/cloud-builders/docker'
  args: ['push', '[MY-USER]/myubuntu']

secrets:
- kmsKeyName: projects/[PROJECT-ID]/locations/global/keyRings/[KEYRING-NAME]/cryptoKeys/[KEY-NAME]
  secretEnv:
    PASSWORD: <base64-encoded encrypted Dockerhub password>

Neste exemplo, a etapa docker login faz login no Dockerhub usando o nome de usuário especificado e a senha descriptografada do Dockerhub, para que a próxima etapa possa docker push a imagem do repositório do usuário para o Dockerhub usando essas credenciais.

A seguir