Membuat pengesahan

Halaman ini menjelaskan langkah-langkah untuk membuat pengesahan Otorisasi Biner.

Anda menggunakan pengesahan untuk mengizinkan image container tertentu di-deploy di platform, seperti Google Kubernetes Engine (GKE) dan Cloud Run. Untuk menggunakan pengesahan, Anda harus mewajibkan pengesahan dalam aturan yang sesuai dalam kebijakan Anda.

Satu pengesahan dapat mengizinkan image identik yang disimpan di beberapa lokasi atau registry yang berbeda, seperti Artifact Registry, Container Registry, atau container registry eksternal.

Pada waktu deployment, Otorisasi Biner menggunakan attestor untuk memverifikasi pengesahan.

Untuk menyiapkan Otorisasi Biner di Cloud Run, GKE, cluster GKE, dan Anthos Service Mesh, lihat Menyiapkan berdasarkan platform dan pilih platform Anda.

Pengguna GKE: Untuk tutorial menyeluruh yang menjelaskan penerapan berbasis pengesahan menggunakan Otorisasi Biner dan Google Kubernetes Engine (GKE), lihat bagian Memulai penggunaan alat command line atau Mulai menggunakan Konsol Google Cloud.

Sebelum memulai

Ringkasan pengesahan menyediakan langkah-langkah yang harus diselesaikan sebelum membuat pengesahan.

Menyiapkan lingkungan

1. Tentukan project ID Anda:

   ATTESTOR_PROJECT_ID=ATTESTOR_PROJECT_ID
   ATTESTATION_PROJECT_ID=ATTESTATION_PROJECT_ID
   

   Ganti kode berikut:

   • ATTESTOR_PROJECT_ID: nama project tempat Anda menyimpan attestor
   • ATTESTATION_PROJECT_ID: nama project tempat Anda menyimpan pengesahan

   Jika Anda ingin pengesahan dibuat dalam project yang sama dengan attestor, gunakan project ID yang sama untuk kedua variabel. Untuk tutorial menyeluruh yang menunjukkan pemisahan tugas dengan berbagai project, lihat Penyiapan multi-project.

2. Tentukan nama attestor dan informasi gambar:

   ATTESTOR_NAME=ATTESTOR_NAME
   IMAGE_PATH=IMAGE_PATH
   IMAGE_DIGEST=IMAGE_DIGEST
   IMAGE_TO_ATTEST="${IMAGE_PATH}@${IMAGE_DIGEST}"
   

   Ganti kode berikut:

   • ATTESTOR_NAME: nama attestor, misalnya, build-secure atau prod-qa.

   • IMAGE_PATH: URI yang mewakili jalur gambar. Meskipun URI harus terdiri dari nama domain dan gambar, URI tidak perlu merujuk ke gambar sebenarnya. Gambar tidak diakses selama pembuatan pengesahan. Berikut adalah contoh jalur gambar:

     • us-docker.pkg.dev/google-samples/containers/gke/hello-app
     • gcr.io/example-project/quickstart-image
     • example.com/hello-app.

   • IMAGE_DIGEST: ringkasan manifes gambar. Misalnya, sha256:37e5287945774f27b418ce567cd77f4bbc9ef44a1bcd1a2312369f31f9cce567 adalah ringkasan gambar yang terkait dengan contoh jalur gambar us-docker.pkg.dev/google-samples/containers/gke/hello-app. Untuk mempelajari cara mendapatkan ringkasan image di Artifact Registry, lihat Mengelola image; untuk image di Container Registry, lihat Mencantumkan versi image.

Memberikan peran Identity and Access Management

Untuk membuat pengesahan, Anda harus memberikan peran Identity and Access Management (IAM) berikut kepada identity yang membuat attestor, sebagai berikut:

• roles/containeranalysis.notes.attacher pada resource catatan yang terkait dengan attestor.
• roles/containeranalysis.occurrences.editor pada resource project pengesahan.

Anda membuat pengesahan berdasarkan attestor. Attestor terkait dengan catatan Artifact Analysis. Dengan membuat pengesahan, kemunculan Artifact Analysis akan dibuat dan dilampirkan ke catatan.

Pelajari lebih lanjut cara Memberikan akses.

Untuk mempelajari cara membuat pengesahan di pipeline Cloud Build, lihat Membuat pengesahan menggunakan Kritis Signer.

Membuat pengesahan

Catatan: Contoh gambar dalam panduan ini hanya untuk demonstrasi. Sebaiknya Anda hanya membuat pengesahan untuk gambar yang Anda kelola.

Membuat pengesahan menggunakan kunci yang disimpan secara lokal

Untuk membuat pengesahan yang ditandatangani dengan kunci lokal, lakukan hal berikut:

1. Buat file payload tanda tangan:

   gcloud

   Untuk membuat file payload tanda tangan, masukkan perintah berikut:

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

   File payload berformat JSON akan terlihat mirip dengan output berikut:

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

   REST API

   Buat file payload bernama /tmp/generated_payload.json menggunakan variabel lingkungan yang Anda tetapkan sebelumnya dalam dokumen ini:

   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
   

2. Tanda tangani payload dengan kunci pribadi Anda untuk menghasilkan file tanda tangan.

   Panduan ini menggunakan algoritme Elliptic Curve Digital Signing Algorithm (ECDSA) yang direkomendasikan untuk penandatanganan. Anda juga dapat menggunakan algoritma RSA. Untuk informasi selengkapnya tentang algoritma penandatanganan, lihat Tujuan dan algoritma utama. Panduan ini juga menggunakan format tanda tangan Public-Key Infrastructure (X.509) (PKIX). Anda juga dapat menggunakan PGP.

   PRIVATE_KEY_FILE=PRIVATE_KEY_FILE
   openssl dgst -sha256 -sign ${PRIVATE_KEY_FILE} /tmp/generated_payload.json > /tmp/ec_signature
   

   Ganti PRIVATE_KEY_FILE dengan jalur ke kunci pribadi yang Anda buat saat membuat attestor.

3. Mendapatkan ID kunci publik.

   Anda dapat mengambil ID kunci publik dari attestor dengan memasukkan perintah berikut:

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

4. Buat pengesahan:

   gcloud

   Untuk membuat dan memvalidasi pengesahan, masukkan string berikut:

   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
   

   Flag validate memeriksa apakah pengesahan dapat diverifikasi oleh attestor yang Anda konfigurasi di kebijakan.

   Catatan: ID kunci dapat berupa string apa pun.

   REST API

   Untuk membuat pengesahan:

   1. Ambil attestor yang terkait dengan pengesahan dan ekstrak ID kunci publik yang tersimpan:

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

      Otorisasi Biner menampilkan objek JSON yang mirip dengan yang berikut ini:

      {
        "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": "[e-mail]"
        },
        "updateTime": "2019-06-26T16:58:33.977438Z"
      }
      

      Kunci publik dapat ditemukan di kolom id.

   2. Buat file JSON di /tmp/attestation.json yang menjelaskan pengesahan:

      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
      

   3. Buat pengesahan:

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

Membuat pengesahan menggunakan Cloud KMS

Untuk membuat pengesahan dengan menggunakan Cloud Key Management Service:

1. Buat variabel lingkungan:

   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
   

   Ganti kode berikut:

   • KMS_KEY_PROJECT_ID: ID project tempat kunci Cloud Key Management Service disimpan
   • KMS_KEY_LOCATION: lokasi kunci (global adalah default)
   • KMS_KEYRING_NAME: nama key ring
   • KMS_KEY_NAME: nama kunci
   • KMS_KEY_VERSION: versi kunci

2. Tanda tangani dan buat pengesahan:

   gcloud

   Masukkan perintah berikut:

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

   REST API

   1. Buat file payload bernama /tmp/generated_payload.json menggunakan variabel lingkungan yang Anda tetapkan di atas:

      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
      

   2. Tanda tangani 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
      

      Ganti DIGEST_ALGORITHM dengan algoritme untuk memahami input. Contoh dalam panduan ini menggunakan ringkasan sha256. Anda dapat menggunakan sha256, sha384, atau sha512.

      Dalam contoh ini, output-nya terlihat mirip dengan berikut ini:

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

      Dalam output ini, SIGNATURE adalah tanda tangan file payload berenkode base64.

   3. Simpan tanda tangan dalam variabel lingkungan:

      PAYLOAD_SIGNATURE=PAYLOAD_SIGNATURE
      

   4. Ambil attestor yang atas namanya Anda menandatangani pengesahan dan ekstrak ID kunci publik dan ID catatan yang tersimpan:

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

      Otorisasi Biner menampilkan objek JSON yang mirip dengan yang berikut ini:

      {
        "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": "[e-mail]"
        },
        "updateTime": "2019-06-26T16:58:33.977438Z"
      }
      

      Anda dapat menemukan ID kunci publik di kolom id dan ID catatan di kolom noteReference.

   5. Simpan ID kunci publik dalam variabel lingkungan:

      PUBLIC_KEY_ID="PUBLIC_KEY_ID"
      NOTE_URI="NOTE_URI"
      

      Ganti kode berikut:

      • PUBLIC_KEY_ID: ID kunci publik attestor.
      • NOTE_URI: URI catatan Artifact Analysis yang terkait dengan attestor.

   6. Buat file JSON di /tmp/attestation.json yang menjelaskan pengesahan:

      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
      

   7. Buat pengesahan:

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

Anda telah membuat pengesahan.

Catatan: Pada waktu deployment, pemberlakuan hanya menggunakan ringkasan image untuk memverifikasi pengesahan. Akibatnya, pengesahan ini dapat digunakan untuk men-deploy image yang identik di beberapa lokasi, termasuk image yang disimpan secara lokal, di Artifact Registry, Container Registry, dan di registry eksternal.

Memverifikasi bahwa pengesahan telah dibuat

Untuk memverifikasi bahwa pengesahan telah dibuat, Anda dapat mencantumkan pengesahan yang terkait dengan image.

gcloud

Untuk mengambil daftar pengesahan, masukkan perintah berikut:

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

REST API

Untuk meminta daftar pengesahan, masukkan perintah berikut:

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

Jika ada banyak pengesahan, respons mungkin berisi nilai nextPageToken. Dalam hal ini, Anda dapat mengambil halaman hasil berikutnya dengan mengulangi permintaan, menambahkan parameter kueri pageToken, seperti berikut:

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}

Ganti NEXT_PAGE_TOKEN dengan nilai nextPageToken dalam respons dari permintaan sebelumnya.

Jika nextPageToken kosong, itu berarti tidak ada hasil lagi.

Menghapus pengesahan

Perhatian: Anda tidak boleh menghapus pengesahan untuk beban kerja produksi. Menghapus pengesahan dapat menyebabkan perilaku yang tidak dapat diprediksi. Petunjuk ini ditujukan untuk menghapus pengesahan pengujian, seperti yang dibuat sebelumnya dalam dokumen ini.

Sebelum menghapus pengesahan, Anda harus melakukan hal berikut:

1. Pahami konsekuensi penghapusannya. Menghapus pengesahan pada akhirnya akan memblokir image container yang terkait dengan pengesahan agar tidak di-deploy.

2. Hentikan semua container yang sedang berjalan dan terkait dengan pengesahan yang ingin Anda hapus.

3. Hapus semua salinan pengesahan di mana pun salinan tersebut berada, misalnya pengesahan di repositori Artifact Registry dan Artifact Analysis.

4. Pastikan image yang terpengaruh benar-benar diblokir agar tidak dapat di-deploy dengan mencoba men-deploy ulang gambar tersebut.

Catatan: Untuk keamanan tambahan, sebaiknya hapus pasangan kunci dan attestor terkait.

Untuk menghapus pengesahan, jalankan perintah berikut:

1. Cantumkan pengesahan:

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

   Pengesahan berisi ID kejadian. Output-nya terlihat mirip dengan berikut:

   projects/ATTESTOR_PROJECT_ID/occurrences/OCCURRENCE_ID
   

2. Simpan ID kejadian.

   Simpan ID kemunculan pengesahan yang ingin Anda hapus.

   OCCURRENCE_ID=OCCURRENCE_ID
   

3. Hapus pengesahan:

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

   Verifikasi bahwa pengesahan telah dihapus dengan mencantumkan pengesahan lagi.

Langkah selanjutnya

• Pelajari lebih lanjut Pemisahan tugas dan peran Identity and Access Management.
• Terapkan pemisahan tugas dalam tutorial Penyiapan multi-project (GKE).
• Deploy image container (GKE) ke cluster tempat Otorisasi Biner diaktifkan.
• Deploy image container (Cloud Run) ke cluster tempat Otorisasi Biner diaktifkan.