Membuat pengesahan

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

Anda menggunakan pengesahan untuk memberikan otorisasi pada image container tertentu agar dapat di-deploy di platform, seperti Google Kubernetes Engine (GKE) dan Cloud Run. Untuk menggunakan atestasi, Anda harus mewajibkan atestasi dalam aturan yang sesuai dari kebijakan Anda.

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

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

Untuk menyiapkan Otorisasi Biner di Cloud Run, GKE, Google Distributed Cloud, dan Cloud Service Mesh, lihat Menyiapkan menurut platform dan pilih platform Anda.

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

Sebelum memulai

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

1. Mengaktifkan Otorisasi Biner

2. Buat pengautentikasi menggunakan Konsol Google Cloud, Google Cloud CLI, atau REST API.

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 pengautentikasi
   • ATTESTATION_PROJECT_ID: nama project tempat Anda menyimpan pengesahan

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

2. Tentukan nama dan informasi gambar pengautentikasi:

   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 pengautentikasi, misalnya, build-secure atau prod-qa.

   • IMAGE_PATH: URI yang mewakili jalur gambar. Meskipun URI harus terdiri dari domain dan nama gambar, URI tersebut tidak perlu merujuk ke gambar yang 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 image. 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 ke identitas yang membuat pengesah, sebagai berikut:

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

Anda membuat pengesahan berdasarkan pengautentikasi. Pengesah dikaitkan dengan catatan Artifact Analysis. Membuat pengesahan akan membuat kemunculan Analisis Artefak dan melampirkan 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 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 membuat file tanda tangan.

   Panduan ini menggunakan algoritma Elliptic Curve Digital Signature Algorithm (ECDSA) yang direkomendasikan untuk penandatanganan. Anda juga dapat menggunakan algoritma RSA. Untuk informasi selengkapnya tentang algoritma penandatanganan, lihat Tujuan dan algoritma kunci. Panduan ini juga menggunakan format tanda tangan Infrastruktur Kunci Publik (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 pengautentikasi.

3. Dapatkan ID kunci publik.

   Anda dapat mengambil ID kunci publik dari pengautentikasi 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 hal 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 penegasnya yang Anda konfigurasi dalam kebijakan.

   Catatan: ID kunci dapat berupa string apa pun.

   REST API

   Untuk membuat pengesahan:

   1. Ambil attestor yang terkait dengan atestasi dan ekstrak ID kunci publik yang disimpan:

      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 berikut:

      {
        "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 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 Anda 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 algoritma untuk mencerna 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 berenkode base64 dari file payload.

   3. Simpan tanda tangan dalam variabel lingkungan:

      PAYLOAD_SIGNATURE=PAYLOAD_SIGNATURE
      

   4. Ambil attestor atas nama siapa Anda menandatangani pengesahan dan ekstrak ID kunci publik dan ID catatan yang disimpan:

      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 berikut:

      {
        "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 pengautentikasi.
      • NOTE_URI: URI catatan Analisis Artefak yang terkait dengan pengautentikasi.

   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, penegak hanya menggunakan ringkasan image untuk memverifikasi atestasi. Akibatnya, pengesahan ini dapat digunakan untuk men-deploy image yang identik di beberapa lokasi, termasuk 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, sebagai 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, berarti tidak ada lagi hasil.

Menghapus pengesahan

Perhatian: Anda tidak boleh menghapus pengesahan untuk workload produksi. Menghapus pengesahan dapat menyebabkan perilaku yang tidak dapat diprediksi. Petunjuk ini adalah 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 deployment image container yang terkait dengan pengesahan tersebut.

2. Hentikan semua penampung yang 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 gambar yang terpengaruh benar-benar diblokir agar tidak di-deploy dengan mencoba men-deploy ulang gambar tersebut.

Catatan: Untuk keamanan tambahan, pertimbangkan untuk menghapus pasangan kunci dan penanda tangan yang terkait.

Untuk menghapus pengesahan, jalankan perintah berikut:

1. Mencantumkan pengesahan:

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

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

   projects/ATTESTOR_PROJECT_ID/occurrences/OCCURRENCE_ID
   

2. Simpan ID kemunculan.

   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) ini.
• Deploy image container (GKE) ke cluster tempat Otorisasi Biner diaktifkan.
• Deploy image container (Cloud Run) ke cluster tempat Otorisasi Biner diaktifkan.