Criar atestadores usando a CLI gcloud

Nesta página, explicamos como criar um atestador na autorização binária usando a Google Cloud CLI. Como alternativa, você pode seguir essas etapas usando o console do Google Cloud ou a API REST. Essa tarefa faz parte da configuração da autorização binária.

Usuários do Cloud Build: é possível usar o atestador built-by-cloud-build para implantar apenas imagens criadas pelo Cloud Build.

Um atestador é um recurso do Google Cloud que a autorização binária usa para verificar um atestado. Para saber mais sobre atestados, consulte Visão geral da autorização binária.

Para criar um atestador, faça o seguinte:

Crie uma nota no Artifact Analysis para armazenar metadados de confiança usados no processo de atestado.
Configure um par de chaves PKIX que possa ser usado para verificar a identidade do atestador. Os pares de chaves assimétricas gerados pelo Cloud Key Management Service (Cloud KMS) estão no formato compatível com PKIX.
Crie o próprio atestador na autorização binária e associe a nota e a chave pública que você criou.

Em uma configuração de projeto único, crie o atestador no mesmo projeto do Google Cloud em que você configura a política de autorização binária. Para ver um tutorial completo de um único projeto que inclui essas etapas, consulte Comece a usar a Google Cloud CLI ou Comece a usar o console do Google Cloud.

Em uma configuração de vários projetos, recomendamos ter projetos separados: um projeto do implantador, em que a política está configurada; um projeto de atestador em que seus atestadores estão armazenados; e um projeto de atestado para atestados. Para ver um tutorial completo de vários projetos que inclui essas etapas, consulte Configuração de vários projetos.

Antes de começar

Antes de criar atestadores, faça o seguinte:

configurar o ambiente do projeto

Nesta seção, você vai configurar variáveis de ambiente.

Configure variáveis de ambiente para armazenar os nomes e números do projeto. Se os projetos de atestador e implantador forem o mesmo, use o mesmo código do projeto para as duas variáveis.

DEPLOYER_PROJECT_ID=DEPLOYER_PROJECT_ID=
DEPLOYER_PROJECT_NUMBER="$(
    gcloud projects describe "${DEPLOYER_PROJECT_ID}" \
      --format="value(projectNumber)"
)"

ATTESTOR_PROJECT_ID=ATTESTOR_PROJECT_ID
ATTESTOR_PROJECT_NUMBER="$(
    gcloud projects describe "${ATTESTOR_PROJECT_ID}" \
    --format="value(projectNumber)"
)"

Você também precisa receber os nomes das contas de serviço dos projetos:

DEPLOYER_SERVICE_ACCOUNT="service-${DEPLOYER_PROJECT_NUMBER}@gcp-sa-binaryauthorization.iam.gserviceaccount.com"
ATTESTOR_SERVICE_ACCOUNT="service-${ATTESTOR_PROJECT_NUMBER}@gcp-sa-binaryauthorization.iam.gserviceaccount.com"

Criar uma nota do Artifact Analysis

A autorização binária usa o Artifact Analysis para armazenar metadados confiáveis usados no processo de autorização. Para cada atestador criado, você precisa criar uma nota do Artifact Analysis. Cada atestado é armazenado como uma ocorrência dessa nota.

Para criar uma nota, siga estas etapas:

Configure variáveis de ambiente para armazenar o código da nota e uma descrição legível:
```
NOTE_ID=NOTE_ID
NOTE_URI="projects/${ATTESTOR_PROJECT_ID}/notes/${NOTE_ID}"
DESCRIPTION=DESCRIPTION
```
Substitua:
- NOTE_ID: o nome interno da nota em caracteres alfanuméricos sem espaços (por exemplo, test-attestor-note).
- NOTE_URI: o caminho totalmente qualificado para o recurso de nota.
- DESCRIPTION: um nome de exibição legível para a observação (por exemplo, Test Attestor Note).

Em um editor de texto, crie um arquivo JSON que descreva a nota:

cat > /tmp/note_payload.json << EOM
{
  "name": "${NOTE_URI}",
  "attestation": {
    "hint": {
      "human_readable_name": "${DESCRIPTION}"
    }
  }
}
EOM

Envie uma solicitação HTTP para a API REST do Artifact Analysis para criar a nota:

curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"  \
    -H "x-goog-user-project: ${ATTESTOR_PROJECT_ID}" \
    --data-binary @/tmp/note_payload.json  \
    "https://containeranalysis.googleapis.com/v1/projects/${ATTESTOR_PROJECT_ID}/notes/?noteId=${NOTE_ID}"

Para verificar se a nota foi criada com sucesso, execute o seguinte comando:

curl \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"  \
    -H "x-goog-user-project: ${ATTESTOR_PROJECT_ID}" \
    "https://containeranalysis.googleapis.com/v1/projects/${ATTESTOR_PROJECT_ID}/notes/"

Definir permissões do IAM na nota

É preciso conceder um papel de Identity and Access Management (IAM) à conta de serviço do projeto do atestador no recurso de nota do Artifact Analysis. Para fazer isso, adicione a conta de serviço do projeto do atestador ao papel containeranalysis.notes.occurrences.viewer na política de IAM da nota.

Para adicionar o papel, faça o seguinte:

Gere um arquivo JSON que contenha as informações necessárias para definir a política do IAM na sua nota:

cat > /tmp/iam_request.json << EOM
{
  "resource": "${NOTE_URI}",
  "policy": {
    "bindings": [
      {
        "role": "roles/containeranalysis.notes.occurrences.viewer",
        "members": [
          "serviceAccount:${ATTESTOR_SERVICE_ACCOUNT}"
        ]
      }
    ]
  }
}
EOM

Adicione a conta de serviço e os papéis de acesso solicitados à política do IAM para a nota que você criou:
```
curl -X POST  \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "x-goog-user-project: ${ATTESTOR_PROJECT_ID}" \
    --data-binary @/tmp/iam_request.json \
    "https://containeranalysis.googleapis.com/v1/projects/${ATTESTOR_PROJECT_ID}/notes/${NOTE_ID}:setIamPolicy"
```
Observação: quando você adiciona um papel à política usando o método acima, ele substitui todos os papéis existentes na observação. Se você quiser preservar os papéis atuais, inclua-os no arquivo de dados JSON anterior.

Uso de vários projetos

Se você armazenar o atestador em um projeto e o implantar em um projeto separado, será necessário conceder o papel roles/binaryauthorization.attestorsVerifier à conta de serviço associada ao projeto do implantador no atestador.

Configurar chaves criptográficas

A autorização binária permite que você use chaves PKIX para verificar atestados.

Gerar um par de chaves

Neste guia, o algoritmo de assinatura digital de curva elíptica (ECDSA, na sigla em inglês) recomendado é usado para gerar um par de chaves PKIX. Também é possível usar pares de chaves RSA ou PGP. Consulte Principais finalidades e algoritmos para mais informações sobre algoritmos de assinatura.

Um par de chaves PKIX é composto por uma chave privada que os assinantes usam para assinar atestados e uma chave pública adicionada ao atestador. No momento da implantação, a autorização binária usa essa chave pública para verificar o atestado.

PKIX (Cloud KMS)

Para criar o par de chaves no Cloud KMS, faça o seguinte:

Para configurar as variáveis de ambiente necessárias para criar o par de chaves, execute os seguintes comandos:
```
KMS_KEY_PROJECT_ID=KMS_KEY_PROJECT_ID
KMS_KEY_LOCATION=KMS_KEY_LOCATION
KMS_KEYRING_NAME=KMS_KEYRING_NAME
KMS_KEY_NAME=KMS_KEY_NAME
KMS_KEY_VERSION=KMS_KEY_VERSION
KMS_KEY_PURPOSE=asymmetric-signing
KMS_KEY_ALGORITHM=KMS_KEY_ALGORITHM
KMS_PROTECTION_LEVEL=KMS_PROTECTION_LEVEL
```
Substitua:
- KMS_KEY_PROJECT_ID: o ID do projeto em que as chaves são armazenadas
- KMS_KEY_LOCATION: a localização da chave;
- KMS_KEYRING_NAME: o nome do keyring;
- KMS_KEY_NAME: o nome da chave;
- KMS_KEY_VERSION: a versão da chave.
- KMS_KEY_ALGORITHM: o algoritmo; o ec-sign-p256-sha256 é recomendado.
- KMS_PROTECTION_LEVEL: o nível de proteção, por exemplo, software.

Para criar o keyring, execute o seguinte comando:

gcloud kms keyrings create ${KMS_KEYRING_NAME} \
    --location ${KMS_KEY_LOCATION}

Para criar a chave, execute o seguinte comando:
```
gcloud kms keys create ${KMS_KEY_NAME} \
    --location ${KMS_KEY_LOCATION} \
    --keyring ${KMS_KEYRING_NAME}  \
    --purpose ${KMS_KEY_PURPOSE} \
    --default-algorithm ${KMS_KEY_ALGORITHM} \
    --protection-level ${KMS_PROTECTION_LEVEL}
```
Substitua:
- KMS_KEY_NAME: o nome da chave;
- KMS_KEY_LOCATION: a localização da chave;
- KMS_KEYRING_NAME: o nome do keyring;
- KMS_KEY_PURPOSE: a finalidade da chave, definida como ASYMMETRIC_SIGN.
- KMS_KEY_ALGORITHM: o algoritmo, o ec-sign-p256-sha256 é recomendado.
- KMS_PROTECTION_LEVEL: o nível de proteção, por exemplo, software.

PKIX (chave local)

Para gerar um novo par de chaves PKIX assimétricas locais e armazená-lo em um arquivo, faça o seguinte:

Gerar a chave privada:

PRIVATE_KEY_FILE é o nome do arquivo que contém a chave privada usada para assinar o payload do atestado.
```
PRIVATE_KEY_FILE="/tmp/ec_private.pem"
openssl ecparam -genkey -name prime256v1 -noout -out ${PRIVATE_KEY_FILE}
```
Extraia a chave pública da chave privada e armazene-a em um arquivo:

PUBLIC_KEY_FILE é o nome do arquivo que contém a chave pública armazenada no atestador.
```
PUBLIC_KEY_FILE="/tmp/ec_public.pem"
openssl ec -in ${PRIVATE_KEY_FILE} -pubout -out ${PUBLIC_KEY_FILE}
```

Crie o atestador

Para criar o atestador, siga estas etapas:

Configure uma variável de ambiente para armazenar o nome do atestador conforme definido na autorização binária:
```
ATTESTOR_NAME=ATTESTOR_NAME
```
em que ATTESTOR_NAME é o nome do atestador que você quer criar (por exemplo, build-secure ou prod-qa).

Crie o recurso de atestador na autorização binária:

gcloud --project="${ATTESTOR_PROJECT_ID}" \
    container binauthz attestors create "${ATTESTOR_NAME}" \
    --attestation-authority-note="${NOTE_ID}" \
    --attestation-authority-note-project="${ATTESTOR_PROJECT_ID}"

Adicione uma vinculação de papel do IAM ao projeto do implantador ao atestador. Isso é usado pela autorização binária quando avalia uma política para determinar se o projeto tem permissões para acessar os atestados associados.

gcloud container binauthz attestors add-iam-policy-binding \
    "projects/${ATTESTOR_PROJECT_ID}/attestors/${ATTESTOR_NAME}" \
    --member="serviceAccount:${DEPLOYER_SERVICE_ACCOUNT}" \
    --role=roles/binaryauthorization.attestorsVerifier

Para adicionar a chave pública ao atestador, faça o seguinte:
PKIX (Cloud KMS)
Para adicionar a chave pública de um par de chaves do Cloud KMS ao atestador, execute o seguinte comando:
```
gcloud --project="${ATTESTOR_PROJECT_ID}" \
    container binauthz attestors public-keys add \
    --attestor="${ATTESTOR_NAME}" \
    --keyversion-project="${KMS_KEY_PROJECT_ID}" \
    --keyversion-location="${KMS_KEY_LOCATION}" \
    --keyversion-keyring="${KMS_KEYRING_NAME}" \
    --keyversion-key="${KMS_KEY_NAME}" \
    --keyversion="${KMS_KEY_VERSION}"
```
PKIX (chave local)
Para adicionar uma chave pública PKIX armazenada localmente a um atestador, execute o seguinte comando:
```
gcloud --project="${ATTESTOR_PROJECT_ID}" \
    container binauthz attestors public-keys add \
    --attestor="${ATTESTOR_NAME}" \
    --pkix-public-key-file=${PUBLIC_KEY_FILE} \
    --pkix-public-key-algorithm=ecdsa-p256-sha256
```
Se você adicionar uma chave pública a um atestador e não especificar um código de chave (que pode ser qualquer string), ele receberá um automaticamente no formato RFC 6920: ni:///sha-256;..., em que ... é um hash codificado da chave pública. Esse valor é retornado no campo id da saída do comando. O código retornado pode ser salvo em PUBLIC_KEY_ID e usado para criar um atestado.

Salve o código da chave pública.

Para criar um atestado, você precisa do ID da chave pública.

Para salvar o ID da chave pública, copie-o na saída do comando binauthz attestors public-keys add acima.

Como alternativa, é possível visualizar o ID de chave pública do atestador a qualquer momento usando o comando a seguir:

gcloud container binauthz attestors describe ${ATTESTOR}.

Para salvar o ID da chave pública em uma variável de ambiente, digite o seguinte comando:

PUBLIC_KEY_ID=$(gcloud container binauthz attestors describe ${ATTESTOR_NAME} \
--format='value(userOwnedGrafeasNote.publicKeys[0].id)')

Verificar se o atestador foi criado

Para verificar se o atestador foi criado, execute este comando:

gcloud container binauthz attestors list \
    --project="${ATTESTOR_PROJECT_ID}"

A seguir

Saiba como criar atestados para o atestador.
Atualize a política de autorização binária para exigir atestados usando o console do Google Cloud, a CLI do Google Cloud e a API REST. ,