Creare attestatori utilizzando l'API REST

Questa pagina spiega come creare un attestatore personalizzato in Autorizzazione binaria utilizzando l'API REST.

In alternativa, puoi eseguire questi passaggi anche utilizzando Google Cloud CLI o la console Google Cloud. Questa attività fa parte della configurazione di Autorizzazione binaria.

Utenti Cloud Build: puoi utilizzare invece l'attestatore built-by-cloud-build per eseguire il deployment solo delle immagini create da Cloud Build.

Panoramica

Un attestatore è una risorsa di Google Cloud che Autorizzazione binaria utilizza per verificare un'attestazione. Per scoprire di più sulle attestazioni, consulta la panoramica di Autorizzazione binaria.

Per creare un attestatore, devi:

  • Crea una nota in Artifact Analysis per archiviare i metadati attendibili utilizzati nel processo di attestazione.
  • Impostare una coppia di chiavi PKIX da utilizzare per verificare l'identità dell'attestatore. Le coppie di chiavi asimmetriche generate da Cloud Key Management Service (Cloud KMS) sono in formato compatibile con PKIX. Puoi anche usare coppie di chiavi PGP anziché chiavi PKIX.
  • Crea l'attestatore in Autorizzazione binaria e associa la nota e la chiave pubblica che hai creato.

In una configurazione per un singolo progetto, crei l'attestatore nello stesso progetto Google Cloud in cui configuri il criterio di Autorizzazione binaria. In una configurazione con più progetti, è probabile che tu abbia un progetto di deployment in cui è configurato il criterio e un progetto attestatore separato in cui sono archiviati gli attestatori.

Prima di iniziare

  1. Abilita Autorizzazione binaria.

  2. Configura Autorizzazione binaria per la tua piattaforma.

Imposta il progetto predefinito

Imposta il progetto Google Cloud predefinito se non lo hai già fatto:

PROJECT_ID=PROJECT_ID
gcloud config set project ${PROJECT_ID}

Configura l'ambiente

Configura le variabili di ambiente per archiviare i nomi e i numeri dei progetti:

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

Se il progetto attestatore e deploymenter sono nello stesso progetto, utilizza lo stesso ID progetto per entrambe le variabili.

Devi anche recuperare i nomi degli account di servizio per i progetti:

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"

Crea una nota Artifact Analysis

Autorizzazione binaria utilizza Artifact Analysis per archiviare i metadati attendibili utilizzati nel processo di autorizzazione. Per ogni attestatore creato, devi creare una nota Artifact Analysis. Ogni attestazione viene archiviata come occorrenza di questa nota.

Per creare una nota Artifact Analysis:

  1. Imposta le variabili di ambiente per archiviare l'ID nota e una descrizione leggibile:

    NOTE_ID=NOTE_ID
    NOTE_URI="projects/${ATTESTOR_PROJECT_ID}/notes/${NOTE_ID}"
    DESCRIPTION=DESCRIPTION
    

    Sostituisci quanto segue:

    • NOTE_ID è il nome interno della nota in caratteri alfanumerici senza spazi (ad esempio, test-attestor-note)
    • NOTE_URI è il percorso completo della risorsa nota
    • DESCRIPTION è un nome visualizzato leggibile per la nota (ad esempio, Test Attestor Note)
  2. In un editor di testo, crea un file JSON in /tmp/note_payload.json che descrivi la nota di Artifact Analysis:

    cat > /tmp/note_payload.json << EOM
    {
      "name": "${NOTE_URI}",
      "attestation": {
        "hint": {
          "human_readable_name": "${DESCRIPTION}"
        }
      }
    }
    EOM
    
  3. Crea la nota inviando una richiesta HTTP all'API REST Artifact 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}"
    

Per verificare che la nota sia stata creata correttamente, esegui questo 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/"

Imposta le autorizzazioni nella nota

Devi anche impostare le autorizzazioni nella nota Artifact Analysis che hai creato in modo che sia accessibile all'account di servizio del progetto attestatore. Per farlo, aggiorna il criterio IAM per la nota per assegnare il ruolo containeranalysis.notes.occurrences.viewer all'account.

Per impostare le autorizzazioni:

  1. Genera un file JSON contenente le informazioni necessarie per impostare il criterio IAM sulla tua 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. Aggiungi l'account di servizio e i ruoli di accesso richiesti al criterio IAM per la nota che hai creato:

    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"
    

Configurazione delle chiavi di crittografia

Autorizzazione binaria consente di utilizzare le chiavi PKIX per verificare in modo sicuro l'identità del firmatario che ha creato un'attestazione. In questo modo solo le parti verificate possono autorizzare un'immagine container. In alternativa a PKIX, puoi usare anche chiavi PGP.

Creare una coppia di chiavi PKIX

Autorizzazione binaria consente di utilizzare coppie di chiavi PKIX asimmetriche per verificare un'attestazione. La coppia di chiavi è composta da una chiave privata, utilizzata dal firmatario per firmare digitalmente le attestazioni e da una chiave pubblica, che aggiungi all'attestatore. In seguito, il responsabile dell'applicazione di Autorizzazione binaria utilizza la chiave pubblica dell'attestatore per verificare che l'attestazione sia stata creata dal firmatario.

In questa guida, viene utilizzato l'algoritmo ECDSA (Elliptic Curve Digital Signing Algorithm) per generare una coppia di chiavi PKIX. Puoi anche usare chiavi RSA o PGP per la firma. Consulta Scopi e algoritmi chiave per ulteriori informazioni sugli algoritmi di firma.

Le coppie di chiavi asimmetriche generate e archiviate in Cloud KMS sono conformi al formato PKIX. Per creare una chiave Cloud KMS da utilizzare con Autorizzazione binaria, consulta Creazione di chiavi asimmetriche. Assicurati di scegliere Segno asimmetrico come scopo della chiave quando crei la chiave.

PKIX (Cloud KMS)

Per creare la coppia di chiavi in Cloud KMS, segui questi passaggi:

  1. Per impostare le variabili di ambiente necessarie per creare la coppia di chiavi, esegui questi comandi:

    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
    

    Sostituisci quanto segue:

    • KMS_KEY_PROJECT_ID: l'ID del progetto in cui sono archiviate le chiavi.
    • KMS_KEY_LOCATION: posizione della chiave
    • KMS_KEYRING_NAME: il nome del keyring
    • KMS_KEY_NAME: il nome della chiave
    • KMS_KEY_VERSION: la versione della chiave
    • KMS_KEY_ALGORITHM: l'algoritmo; è consigliato ec-sign-p256-sha256
    • KMS_PROTECTION_LEVEL: il livello di protezione, ad esempio software
  2. Per creare il keyring, esegui questo comando:

    gcloud kms keyrings create ${KMS_KEYRING_NAME} \
        --location ${KMS_KEY_LOCATION}
    
  3. Per creare la chiave, esegui questo 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}
    

PKIX (chiave locale)

Per generare una nuova coppia di chiavi PKIX asimmetrica locale e memorizzarla in un file:

  1. Genera la chiave:

    PRIVATE_KEY_FILE="/tmp/ec_private.pem"
    openssl ecparam -genkey -name prime256v1 -noout -out ${PRIVATE_KEY_FILE}
    
  2. Poiché questo file contiene una chiave pubblica e una privata, devi estrarre la chiave pubblica in un file separato in modo da poterla aggiungere all'attestatore:

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

Crea l'attestatore

Il passaggio successivo prevede la creazione dell'attestatore stesso in Autorizzazione binaria con la nota Artifact Analysis associata. Devi anche aggiungere la chiave pubblica crittografica.

Per creare l'attestatore:

  1. Configura una variabile di ambiente per archiviare il nome dell'attestatore come definito in Autorizzazione binaria:

    ATTESTOR_NAME=ATTESTOR_NAME
    

    dove ATTESTOR_NAME è il nome dell'attestatore che vuoi creare (ad esempio, build-secure o prod-qa).

  2. Crea l'attestatore e allega il token di sicurezza pubblico:

    PKIX (Cloud KMS)

    1. Configura variabili di ambiente aggiuntive per archiviare informazioni sulla coppia di chiavi Cloud KMS per la chiamata all'API Autorizzazione binaria.

      KMS_CRYPTO_KEY_URI="projects/${KMS_KEY_PROJECT_ID}/locations/${KMS_KEY_LOCATION}/keyRings/${KMS_KEYRING_NAME}/cryptoKeys/${KMS_KEY_NAME}"
      KMS_CRYPTO_KEY_VERSION_URI="${KMS_CRYPTO_KEY_URI}/cryptoKeyVersions/${KMS_KEY_VERSION}"
      KMS_KEY_ID="//cloudkms.googleapis.com/v1/${KMS_CRYPTO_KEY_VERSION_URI}"
      
    2. Scarica il file della chiave pubblica da Cloud KMS e salvalo in un file denominato /tmp/kms_public_key.pem nel tuo sistema locale.

    3. Genera un file JSON contenente le informazioni necessarie per creare l'attestatore:

      cat > /tmp/attestor.json << EOM
      {
          "userOwnedDrydockNote": {
              "noteReference": "${NOTE_URI}",
              "publicKeys": {
                  "id": "${KMS_KEY_ID}",
                  "pkixPublicKey": {
                      "signatureAlgorithm": "${KMS_KEY_ALGORITHM}",
                      "publicKeyPem": $( \
                          python < /tmp/kms_public_key.pem \
                          -c 'import json, sys; print(json.dumps(sys.stdin.read()))' \
                      )
                  }
              }
          }
      }
      EOM
      
    4. Crea l'attestatore:

      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/attestor.json \
      "https://binaryauthorization.googleapis.com/v1/projects/${ATTESTOR_PROJECT_ID}/attestors?attestorId=${ATTESTOR_NAME}"
      

    PKIX (chiave locale)

    1. Genera un file JSON contenente le informazioni necessarie per creare l'attestatore:

      cat > /tmp/attestor.json << EOM
      {
         "userOwnedGrafeasNote": {
             "noteReference": "${NOTE_URI}",
             "publicKeys": {
                 "pkixPublicKey": {
                     "signatureAlgorithm": "ecdsa_p256_sha256",
                     "publicKeyPem": $( \
                         python < ${PUBLIC_KEY_FILE} \
                         -c 'import json, sys; print(json.dumps(sys.stdin.read()))' \
                     )
                 }
             }
         }
      }
      EOM
      
    2. Crea l'attestatore:

      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/attestor.json \
      "https://binaryauthorization.googleapis.com/v1/projects/${ATTESTOR_PROJECT_ID}/attestors?attestorId=${ATTESTOR_NAME}"
      
  3. Aggiungi all'attestatore un'associazione del ruolo IAM per il progetto deployer. Viene utilizzato da Autorizzazione binaria quando valuta un criterio per determinare se il progetto dispone delle autorizzazioni per accedere all'attestatore a cui viene fatto riferimento.

    Genera un file JSON contenente le informazioni necessarie per impostare il criterio IAM sull'attestatore:

    cat > /tmp/iam_request.json << EOM
    {
      'resource': 'projects/${ATTESTOR_PROJECT_ID}/attestors/${ATTESTOR_NAME}',
      'policy': {
        'bindings': [
          {
            'role': 'roles/binaryauthorization.attestorsVerifier',
            'members': [
              'serviceAccount:${DEPLOYER_SERVICE_ACCOUNT}'
            ]
          }
        ]
      }
    }
    EOM
    

    Aggiungi l'account di servizio e i ruoli di accesso richiesti al criterio IAM per la nota che hai creato:

    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://binaryauthorization.googleapis.com/v1beta1/projects/${ATTESTOR_PROJECT_ID}/attestors/${ATTESTOR_NAME}:setIamPolicy"
    

Verificare che l'attestatore sia stato creato

Per verificare che l'attestatore sia stato creato, esegui questo comando:

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

Passaggi successivi