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:

  1. Ativar autorização binária.

  2. Configurar a autorização binária para sua plataforma.

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:

  1. 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).
  2. 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
    
  3. 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:

  1. 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
    
  2. 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:

  1. 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.
  2. Para criar o keyring, execute o seguinte comando:

    gcloud kms keyrings create ${KMS_KEYRING_NAME} \
        --location ${KMS_KEY_LOCATION}
    
  3. 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:

  1. 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}
    
  2. 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:

  1. 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).

  2. 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}"
    
  3. 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
    
  4. 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