Questa pagina è stata tradotta dall'API Cloud Translation.

Creazione di attestazioni

In questa pagina vengono descritti i passaggi per creare un'attestazione di Autorizzazione binaria.

Puoi utilizzare le attestazioni per autorizzare il deployment di immagini container specifiche su piattaforme come Google Kubernetes Engine (GKE) e Cloud Run. Per utilizzare le attestazioni, devi richiedere le attestazioni nella regola appropriata del tuo criterio.

Una singola attestazione può autorizzare immagini identiche archiviate in più posizioni o in registri diversi, ad esempio Artifact Registry, Container Registry o un Container Registry esterno.

Al momento del deployment, Autorizzazione binaria utilizza gli attestatori per verificare le attestazioni.

Per configurare Autorizzazione binaria su Cloud Run, GKE, cluster GKE e Anthos Service Mesh, consulta Configurazione per piattaforma e seleziona la tua piattaforma.

Utenti di GKE: per un tutorial end-to-end che descrive l'applicazione forzata basata su attestazione utilizzando Autorizzazione binaria e Google Kubernetes Engine (GKE), consulta la pagina Guida introduttiva all'utilizzo dello strumento a riga di comando o Guida introduttiva all'utilizzo della console Google Cloud.

Prima di iniziare

La Panoramica delle attestazioni fornisce i passaggi da completare prima di creare un'attestazione.

Abilita Autorizzazione binaria
Crea gli attestatori utilizzando la console Google Cloud, Google Cloud CLI o l'API REST.

Configura l'ambiente

Specifica gli ID progetto:
```
ATTESTOR_PROJECT_ID=ATTESTOR_PROJECT_ID
ATTESTATION_PROJECT_ID=ATTESTATION_PROJECT_ID
```
Sostituisci quanto segue:
- ATTESTOR_PROJECT_ID: il nome del progetto in cui stai memorizzando gli attestatori
- ATTESTATION_PROJECT_ID: nome del progetto in cui archivia le attestazioni
Se vuoi che l'attestazione venga creata nello stesso progetto degli attestatori, utilizza lo stesso ID progetto per entrambe le variabili. Per un tutorial end-to-end che illustra la separazione dei compiti con progetti diversi, consulta Configurazione di più progetti.
Specifica il nome dell'attestatore e le informazioni sull'immagine:
```
ATTESTOR_NAME=ATTESTOR_NAME
IMAGE_PATH=IMAGE_PATH
IMAGE_DIGEST=IMAGE_DIGEST
IMAGE_TO_ATTEST="${IMAGE_PATH}@${IMAGE_DIGEST}"
```
Sostituisci quanto segue:
- ATTESTOR_NAME: il nome dell'attestatore, ad esempio build-secure o prod-qa.
- IMAGE_PATH: un URI che rappresenta il percorso di un'immagine. Anche se l'URI deve includere un dominio e un nome di immagine, non è necessario fare riferimento a un'immagine effettiva. Non è possibile accedere alle immagini durante la creazione dell'attestazione. Di seguito sono riportati alcuni esempi di percorsi delle immagini:
  - us-docker.pkg.dev/google-samples/containers/gke/hello-app
  - gcr.io/example-project/quickstart-image
  - example.com/hello-app.
- IMAGE_DIGEST: il digest del manifest dell'immagine. Ad esempio, sha256:37e5287945774f27b418ce567cd77f4bbc9ef44a1bcd1a2312369f31f9cce567 è il digest dell'immagine associato al percorso dell'immagine us-docker.pkg.dev/google-samples/containers/gke/hello-app di esempio. Per scoprire come ottenere il digest di un'immagine in Artifact Registry, consulta Gestione delle immagini; per un'immagine in Container Registry, consulta Elenco delle versioni di un'immagine.

Concedi ruoli di Identity and Access Management

Per creare attestazioni, devi concedere i seguenti ruoli IAM (Identity and Access Management) all'identità che crea l'attestatore, come indicato di seguito:

roles/containeranalysis.notes.attacher sulla risorsa nota associata all'attestatore.
roles/containeranalysis.occurrences.editor sulla risorsa del progetto di attestazione.

Puoi creare un'attestazione basata su un attestatore. L'attestatore è associato a una nota Artifact Analysis. La creazione di un'attestazione a sua volta crea un'occorrenza di Artifact Analysis e la collega alla nota.

Scopri di più sulla concessione dell'accesso.

Per informazioni su come creare un'attestazione in una pipeline di Cloud Build, consulta Creazione di attestazioni con Kritis Signer.

Crea un'attestazione

Crea un'attestazione utilizzando una chiave archiviata in locale

Per creare un'attestazione firmata con una chiave locale:

Crea un file payload della firma:

gcloud

Per creare il file payload della firma, inserisci il seguente comando:

gcloud container binauthz create-signature-payload \
    --artifact-url="${IMAGE_TO_ATTEST}" > /tmp/generated_payload.json

Il file payload in formato JSON è simile al seguente output:

{
  "critical": {
    "identity": {
      "docker-reference": "us-docker.pkg.dev/google-samples/containers/gke/hello-app"
    },
    "image": {
      "docker-manifest-digest": "sha256:37e5287945774f27b418ce567cd77f4bbc9ef44a1bcd1a2312369f31f9cce567"
    },
    "type": "Google cloud binauthz container signature"
  }
}

API REST

Crea un file payload denominato /tmp/generated_payload.json utilizzando le variabili di ambiente impostate in precedenza in questo documento:

cat > /tmp/generated_payload.json << EOM
{
  "critical": {
    "identity": {
      "docker-reference": "${IMAGE_PATH}"
    },
    "image": {
      "docker-manifest-digest": "${IMAGE_DIGEST}"
    },
    "type": "Google cloud binauthz container signature"
  }
}
EOM

Firma il payload con la tua chiave privata per generare un file di firma.

Questa guida utilizza l'algoritmo consigliato per la firma dell'algoritmo di firma digitale Ellittica Curve (ECDSA). Puoi anche utilizzare l'algoritmo RSA. Per scoprire di più sugli algoritmi di firma, consulta Algoritmi e scopi chiave. Questa guida utilizza anche il formato di firma PKIX (Public-Key Infrastructure (X.509)). Puoi anche utilizzare PGP.
```
PRIVATE_KEY_FILE=PRIVATE_KEY_FILE
openssl dgst -sha256 -sign ${PRIVATE_KEY_FILE} /tmp/generated_payload.json > /tmp/ec_signature
```
Sostituisci PRIVATE_KEY_FILE con il percorso della chiave privata generata al momento della creazione dell'attestatore.

Recupera l'ID della chiave pubblica.

Puoi recuperare l'ID della chiave pubblica dall'attestatore inserendo il seguente comando:

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

Crea l'attestazione:

gcloud

Per creare e convalidare l'attestazione, inserisci quanto segue:

gcloud container binauthz attestations create \
    --project="${ATTESTATION_PROJECT_ID}" \
    --artifact-url="${IMAGE_TO_ATTEST}" \
    --attestor="projects/${ATTESTOR_PROJECT_ID}/attestors/${ATTESTOR_NAME}" \
    --signature-file=/tmp/ec_signature \
    --public-key-id="${PUBLIC_KEY_ID}" \
    --validate

Il flag validate verifica che l'attestazione possa essere verificata dall'attestatore configurato nel criterio.

Nota: l'ID chiave può essere qualsiasi stringa.

API REST

Per creare l'attestazione:

Recupera l'attestatore associato all'attestazione ed estrai l'ID della chiave pubblica archiviata:

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

Autorizzazione binaria restituisce un oggetto JSON simile al seguente:

{
  "name": "projects/example-project/attestors/test-attestor",
  "userOwnedGrafeasNote": {
    "noteReference": "projects/example-project/notes/test-attestor",
    "publicKeys": [
      {
        "id": "ni:///sha-256;EwVxs8fNUAHq9FI2AMfh8WNIXVBuuTMeGtPH72U-I70",
        "pkixPublicKey": {
          "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEXnpuYEfvLl1kj4fjxViFRwY1a+zC\n5qzlf9LJIK+rnjq42tiKGyyXMbnZKJiYPPdMDGyltnkrABnztg2jJ48aYQ==\n-----END PUBLIC KEY-----\n",
          "signatureAlgorithm": "ECDSA_P256_SHA256"
        }
      }
    ],
    "delegationServiceAccountEmail": "service-363451293945@gcp-sa-binaryauthorization.iam.gserviceaccount.com"
  },
  "updateTime": "2019-06-26T16:58:33.977438Z"
}

La chiave pubblica si trova nel campo id.

Crea in /tmp/attestation.json un file JSON che descriva l'attestazione:

cat > /tmp/attestation.json << EOM
{
  "resourceUri": "${IMAGE_TO_ATTEST}",
  "note_name": "${NOTE_URI}",
  "attestation": {
     "serialized_payload": "$(base64 --wrap=0 /tmp/generated_payload.json)",
     "signatures": [
        {
         "public_key_id": "${PUBLIC_KEY_ID}",
         "signature": "$(base64 --wrap=0 /tmp/ec_signature)"
        }
     ]
  }
 }
EOM

Crea l'attestazione:

curl -X POST \
    -H "Content-Type: application/json" \
    -H "X-Goog-User-Project: ${ATTESTATION_PROJECT_ID}" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    --data-binary @/tmp/attestation.json \
    "https://containeranalysis.googleapis.com/v1/projects/${ATTESTATION_PROJECT_ID}/occurrences/"

Crea un'attestazione utilizzando Cloud KMS

Per creare un'attestazione con l'utilizzo di Cloud Key Management Service:

Crea le variabili di ambiente:
```
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
```
Sostituisci quanto segue:
- KMS_KEY_PROJECT_ID: l'ID del progetto in cui sono archiviate le chiavi Cloud Key Management Service
- KMS_KEY_LOCATION: la posizione della chiave (global è la posizione predefinita)
- KMS_KEYRING_NAME: il nome del keyring
- KMS_KEY_NAME: il nome della chiave
- KMS_KEY_VERSION: la versione della chiave

Firma e crea l'attestazione:

gcloud

Inserisci questo comando:

gcloud beta container binauthz attestations sign-and-create \
    --project="${ATTESTATION_PROJECT_ID}" \
    --artifact-url="${IMAGE_TO_ATTEST}" \
    --attestor="${ATTESTOR_NAME}" \
    --attestor-project="${ATTESTOR_PROJECT_ID}" \
    --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}"

API REST

Crea un file payload denominato /tmp/generated_payload.json utilizzando le variabili di ambiente impostate sopra:

cat > /tmp/generated_payload.json << EOM
{
  "critical": {
    "identity": {
      "docker-reference": "${IMAGE_PATH}"
    },
    "image": {
      "docker-manifest-digest": "${IMAGE_DIGEST}"
    },
    "type": "Google cloud binauthz container signature"
  }
}
EOM

Firma il file payload:

curl \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $(gcloud auth print-access-token)" \
  --header "x-goog-user-project: ${ATTESTOR_PROJECT_ID}" \
  --data '{"digest":  {"DIGEST_ALGORITHM": "'$(openssl dgst -sha256 -binary /tmp/generated_payload.json | openssl base64)'" }}' \
https://cloudkms.googleapis.com/v1/projects/${KMS_KEY_PROJECT_ID}/locations/${KMS_KEY_LOCATION}/keyRings/${KMS_KEYRING_NAME}/cryptoKeys/${KMS_KEY_NAME}/cryptoKeyVersions/${KMS_KEY_VERSION}:asymmetricSign?alt=json

Sostituisci DIGEST_ALGORITHM con l'algoritmo per assimilare l'input. Gli esempi di questa guida utilizzano un digest sha256. Puoi utilizzare sha256, sha384 o sha512.

In questo esempio, l'output è simile al seguente:

{
  "signature": "<var>SIGNATURE</var>": "996305066",
  "name": "projects/<var>KMS_KEY_PROJECT_ID</var>/locations/<var>KMS_KEY_LOCATION</var>/keyRings/<var>KMS_KEYRING_NAME</var>/cryptoKeys/<var>KMS_KEY_NAME</var>/cryptoKeyVersions/<var>KMS_KEY_VERSION</var>"
}

In questo output, SIGNATURE è la firma codificata in Base64 del file payload.

Archivia la firma in una variabile di ambiente:
```
PAYLOAD_SIGNATURE=PAYLOAD_SIGNATURE
```

Recupera l'attestatore per conto del quale stai firmando l'attestazione ed estrai l'ID chiave pubblica e l'ID nota archiviati:

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

Autorizzazione binaria restituisce un oggetto JSON simile al seguente:

{
  "name": "projects/example-project/attestors/test-attestor",
  "userOwnedGrafeasNote": {
    "noteReference": "projects/example-project/notes/test-attestor",
    "publicKeys": [
      {
        "id": "ni:///sha-256;EwVxs8fNUAHq9FI2AMfh8WNIXVBuuTMeGtPH72U-I70",
        "pkixPublicKey": {
          "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEXnpuYEfvLl1kj4fjxViFRwY1a+zC\n5qzlf9LJIK+rnjq42tiKGyyXMbnZKJiYPPdMDGyltnkrABnztg2jJ48aYQ==\n-----END PUBLIC KEY-----\n",
          "signatureAlgorithm": "ECDSA_P256_SHA256"
        }
      }
    ],
    "delegationServiceAccountEmail": "service-363451293945@gcp-sa-binaryauthorization.iam.gserviceaccount.com"
  },
  "updateTime": "2019-06-26T16:58:33.977438Z"
}

Puoi trovare l'ID della chiave pubblica nel campo id e l'ID nota nel campo noteReference.

Archivia l'ID della chiave pubblica in una variabile di ambiente:
```
PUBLIC_KEY_ID="PUBLIC_KEY_ID"
NOTE_URI="NOTE_URI"
```
Sostituisci quanto segue:
- PUBLIC_KEY_ID: l'ID della chiave pubblica dell'attestatore.
- NOTE_URI: l'URI della nota di Artifact Analysis associato all'attestatore.

Crea in /tmp/attestation.json un file JSON che descriva l'attestazione:

cat > /tmp/attestation.json << EOM
{
  "resourceUri": "${IMAGE_TO_ATTEST}",
  "note_name": "${NOTE_URI}",
  "attestation": {
     "serialized_payload": "$(base64 --wrap=0 /tmp/generated_payload.json)",
     "signatures": [
         {
             "public_key_id": "${PUBLIC_KEY_ID}",
             "signature": "${PAYLOAD_SIGNATURE}"
         }
     ]
  }
}
EOM

Crea l'attestazione:

curl -X POST \
    -H "Content-Type: application/json" \
    -H "X-Goog-User-Project: ${ATTESTATION_PROJECT_ID}" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    --data-binary @/tmp/attestation.json \
"https://containeranalysis.googleapis.com/v1/projects/${ATTESTATION_PROJECT_ID}/occurrences/"

Hai creato l'attestazione.

Verifica che l'attestazione sia stata creata

Per verificare che l'attestazione sia stata creata, puoi elencare le attestazioni associate all'immagine.

gcloud

Per recuperare un elenco di attestazioni, inserisci il seguente comando:

gcloud container binauthz attestations list\
    --project="${ATTESTATION_PROJECT_ID}"\
    --attestor="projects/${ATTESTOR_PROJECT_ID}/attestors/${ATTESTOR_NAME}"\
    --artifact-url="${IMAGE_TO_ATTEST}"

API REST

Per richiedere un elenco delle attestazioni, inserisci il seguente comando:

curl -X GET \
    -H "Content-Type: application/json" \
    -H "X-Goog-User-Project: ${ATTESTOR_PROJECT_ID}" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://containeranalysis.googleapis.com/v1/projects/${ATTESTOR_PROJECT_ID}/notes/${NOTE_ID}/occurrences?filter=resourceUrl%3D%22https%3A%2F%2F$(jq -rn --arg x ${IMAGE_TO_ATTEST} '$x|@uri')%22

Se sono presenti molte attestazioni, la risposta potrebbe contenere un valore nextPageToken. In questo caso, puoi recuperare la pagina di risultati successiva ripetendo la richiesta e aggiungendo un parametro di query pageToken, come indicato di seguito:

NEXT_PAGE_TOKEN=NEXT_PAGE_TOKEN
curl -X GET \
    -H "Content-Type: application/json" \
    -H "X-Goog-User-Project: ${ATTESTOR_PROJECT_ID}" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://containeranalysis.googleapis.com/v1/projects/${ATTESTOR_PROJECT_ID}/notes/${NOTE_ID}/occurrences?filter=resourceUrl%3D%22https%3A%2F%2F$(jq -rn --arg x ${IMAGE_TO_ATTEST} '$x|@uri')%22&pageToken=${NEXT_PAGE_TOKEN}

Sostituisci NEXT_PAGE_TOKEN con il valore nextPageToken nella risposta alla richiesta precedente.

Se nextPageToken è vuoto, significa che non ci sono altri risultati.

Elimina l'attestazione

Prima di eliminare l'attestazione:

Scopri le implicazioni dell'eliminazione. L'eliminazione di un'attestazione comporta il blocco del deployment delle immagini container associate all'attestazione.
Arresta tutti i container in esecuzione associati alle attestazioni che intendi eliminare.
Eliminare tutte le copie delle attestazioni ovunque si trovino, ad esempio attestazioni nei repository Artifact Registry e Artifact Analysis.
Assicurati che il deployment delle immagini interessate sia effettivamente bloccato provando a eseguirne nuovamente il deployment.

Per eliminare un'attestazione, esegui questi comandi:

Elenca attestazioni:

gcloud container binauthz attestations list \
  --attestor-project=${ATTESTOR_PROJECT_ID} \
  --attestor=${ATTESTOR_NAME}

L'attestazione contiene un ID occorrenza. L'output è simile al seguente:

projects/ATTESTOR_PROJECT_ID/occurrences/OCCURRENCE_ID

Salva l'ID occorrenza.

Salva l'ID occorrenza dell'attestazione da eliminare.
```
OCCURRENCE_ID=OCCURRENCE_ID
```

Elimina l'attestazione:

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -X DELETE \
  https://containeranalysis.googleapis.com/v1beta1/projects/${ATTESTATION_PROJECT_ID}/occurrences/${OCCURRENCE_ID}

Verifica che le attestazioni siano state eliminate elencando di nuovo le attestazioni.

Passaggi successivi

Scopri di più sulla Separazione dei compiti e sui ruoli di Identity and Access Management.
Implementa la separazione dei compiti in questo tutorial sulla configurazione di più progetti (GKE).
Esegui il deployment di un'immagine container (GKE) in un cluster in cui è abilitata Autorizzazione binaria.
Esegui il deployment di un'immagine container (Cloud Run) in un cluster in cui è abilitata Autorizzazione binaria.