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.

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:

A autorização binária precisa estar ativada. Para saber como fazer isso, consulte Como ativar a autorização binária.
A política precisa ser configurada para permitir apenas imagens que são verificadas por atestadores. Para saber como fazer isso, consulte Configurar uma política usando a CLI gcloud.

Configurar um ambiente de 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"

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

Criar atestadores usando a CLI gcloud

Antes de começar

Configurar um ambiente de projeto

Criar uma nota do Artifact Analysis

Definir permissões do IAM na nota

Uso de vários projetos

Configurar chaves criptográficas

Gerar um par de chaves

PKIX (Cloud KMS)

PKIX (chave local)

Crie o atestador

PKIX (Cloud KMS)

PKIX (chave local)

Salve o código da chave pública.

Verificar se o atestador foi criado

A seguir