Criar atestadores usando a ferramenta gcloud

Nesta página, explicamos como criar um atestador na autorização binária usando a ferramenta de linha de comando gcloud. Como alternativa, você também pode executar 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 a Visão geral da autorização binária.

Para criar um atestador, você precisa fazer o seguinte:

  • Crie uma nota no Container 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. Em um configuração de vários projetos, é provável que você tenha projeto do implantador com a política configurada e um recurso Projeto de atestador onde seus atestadores são armazenados.

Configure o ambiente

Configure variáveis de ambiente para armazenar os nomes e números dos seus projetos:

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

Se os projetos de atestador e implantador forem o mesmo, use o mesmo código do projeto para as duas variáveis. Para ver um tutorial completo que descreve a separação de deveres usando vários projetos, consulte Configuração de vários projetos.

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 Container Analysis

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

Para criar uma nota do Container Analysis, 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 em /tmp/note_payload.json que descreva a nota do Container Analysis:

    cat > /tmp/note_payload.json << EOM
    {
      "name": "${NOTE_URI}",
      "attestation": {
        "hint": {
          "human_readable_name": "${DESCRIPTION}"
        }
      }
    }
    EOM
    
  3. Crie a nota enviando uma solicitação HTTP para a API REST do Container Analysis:

    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:

    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 as permissões do gerenciamento de identidade e acesso na nota

Você precisa conceder um papel de gerenciamento de identidade e acesso (IAM) à conta de serviço do projeto do atestador no recurso de observação do Container Analysis. Para fazer isso, adicione a conta de serviço do projeto do atestador ao papel containeranalysis.notes.occurrences.viewer na política do IAM da observação.

Para adicionar o papel:

  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 com segurança a identidade do signer que criou um atestado. Isso garante que apenas as partes verificadas possam autorizar uma imagem de contêiner. Como alternativa ao PKIX, você também pode usar chaves PGP.

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 chaves RSA ou PGP para assinatura. Consulte Finalidades de chave e algoritmos para mais informações sobre algoritmos de assinatura.

Um par de chaves PKIX consiste em uma chave privada, que o signatário usa para assinar atestados digitalmente e uma chave pública, que você adiciona ao atestador. No momento da implantação, a autorização binária usa essa chave pública para verificar o atestado assinado pela chave privada.

Para gerar um novo par de chaves PKIX assimétrica e armazená-lo em um arquivo:

  1. Gere 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 que será armazenada no atestador.

    PUBLIC_KEY_FILE="/tmp/ec_public.pem"
    openssl ec -in ${PRIVATE_KEY_FILE} -pubout -out ${PUBLIC_KEY_FILE}
    

Os pares de chaves assimétricas gerados e armazenados no Cloud KMS são compatíveis com o formato PKIX. Para criar uma chave do Cloud KMS para uso com autorização binária, consulte Como criar chaves assimétricas. Escolha Assinatura assimétrica como a finalidade da chave ao criar a chave.

Criar o atestador

A próxima etapa é criar o próprio atestador na autorização binária com a nota do Container Analysis associada. Também é necessário adicionar a chave pública criptográfica.

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. Adicione a chave pública ao atestador:

    PKIX (chave local)

    1. Adicione uma chave pública PKIX armazenada localmente a um atestador:

      Agora, adicione a chave pública exportada ao atestador para que ela possa ser usada pela autorização binária para verificação de identidade:

      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
      

      Observação: 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.

    2. Salve o código da chave pública.

      Ao criar um atestado, você precisará do código da chave pública. Para salvar o ID da chave pública, salve-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: gcloud container binauthz attestors describe ${ATTESTOR}.

      Para salvar o código da chave pública em uma variável de ambiente, digite este comando:

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

    PKIX (Cloud KMS)

    1. Configure variáveis de ambiente para armazenar informações sobre o par de chaves como gerenciado pelo Cloud KMS:

      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: 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. Recomendamos ec-sign-p256-sha256;
      • KMS_PROTECTION_LEVEL: o nível de proteção, por exemplo, software.
    2. Crie um keyring do Cloud KMS:

      gcloud --project ${KMS_KEY_PROJECT_ID} kms keyrings create \
        ${KMS_KEYRING_NAME} \
        --location ${KMS_KEY_LOCATION}
      
    3. Crie a chave:

      gcloud --project ${KMS_KEY_PROJECT_ID} 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}
      

      Para mais informações sobre como criar chaves do KMS, consulte Criar uma chave assimétrica.

    4. Adicione a chave pública ao atestador:

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

Verificar se o atestador foi criado

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

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

A seguir