Membuat attestor menggunakan REST API

Halaman ini menjelaskan cara membuat attestor dalam Otorisasi Biner menggunakan REST API. Sebagai alternatif, Anda juga dapat melakukan langkah-langkah ini menggunakan Google Cloud CLI atau Google Cloud Console. Tugas ini adalah bagian dari menyiapkan Otorisasi Biner.

Ringkasan

attestor adalah resource Google Cloud yang digunakan oleh Otorisasi Biner untuk memverifikasi pengesahan. Untuk mempelajari pengesahan lebih lanjut, lihat ringkasan Otorisasi Biner.

Untuk membuat attestor, Anda harus melakukan hal-hal berikut:

Buat catatan di Artifact Analysis untuk menyimpan metadata tepercaya yang digunakan dalam proses pengesahan.
Siapkan pasangan kunci PKIX yang dapat digunakan untuk memverifikasi identitas attestor. (Pasangan kunci asimetris yang dihasilkan oleh Cloud Key Management Service (Cloud KMS) memiliki format yang kompatibel dengan PKIX.) Anda juga dapat menggunakan pasangan kunci PGP alih-alih kunci PKIX.
Buat attestor itu sendiri di Otorisasi Biner, lalu kaitkan catatan dan kunci publik yang Anda buat.

Dalam penyiapan project tunggal, Anda membuat attestor di project Google Cloud yang sama, tempat Anda mengonfigurasi kebijakan Otorisasi Biner. Dalam penyiapan multi-project, Anda kemungkinan besar memiliki project deploy tempat kebijakan Anda dikonfigurasi dan project attestor terpisah tempat attestor Anda disimpan.

Menetapkan project default

Tetapkan project Google Cloud default jika Anda belum melakukannya:

PROJECT_ID=PROJECT_ID
gcloud config set project ${PROJECT_ID}

Menyiapkan lingkungan

Siapkan variabel lingkungan untuk menyimpan nama dan nomor project Anda:

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

Jika project attestor dan deployer Anda adalah project yang sama, gunakan project ID yang sama untuk kedua variabel.

Anda juga harus mendapatkan nama akun layanan untuk project tersebut:

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"

Membuat catatan Artifact Analysis

Otorisasi Biner menggunakan Analisis Artefak untuk menyimpan metadata tepercaya yang digunakan dalam proses otorisasi. Untuk setiap attestor yang dibuat, Anda harus membuat satu catatan Artifact Analysis. Setiap pengesahan disimpan sebagai kemunculan catatan ini.

Untuk membuat catatan Analisis Artefak:

Siapkan variabel lingkungan untuk menyimpan ID catatan dan deskripsi yang dapat dibaca manusia:
```
NOTE_ID=NOTE_ID
NOTE_URI="projects/${ATTESTOR_PROJECT_ID}/notes/${NOTE_ID}"
DESCRIPTION=DESCRIPTION
```
Ganti kode berikut:
- NOTE_ID adalah nama internal catatan dalam karakter alfanumerik tanpa spasi (misalnya test-attestor-note)
- NOTE_URI adalah jalur yang sepenuhnya memenuhi syarat ke resource catatan
- DESCRIPTION adalah nama tampilan yang dapat dibaca manusia untuk catatan (misalnya Test Attestor Note)

Di editor teks, buat file JSON di /tmp/note_payload.json yang menjelaskan catatan Artifact Analysis:

cat > /tmp/note_payload.json << EOM
{
  "name": "${NOTE_URI}",
  "attestation": {
    "hint": {
      "human_readable_name": "${DESCRIPTION}"
    }
  }
}
EOM

Buat catatan dengan mengirim permintaan HTTP ke Artifact Analysis REST API:

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

Untuk memastikan bahwa catatan berhasil dibuat, jalankan perintah berikut:

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

Menetapkan izin pada catatan

Anda juga harus menetapkan izin pada catatan Artifact Analysis yang Anda buat sehingga dapat diakses oleh akun layanan project attestor. Anda dapat melakukannya dengan memperbarui kebijakan IAM untuk catatan guna menetapkan peran containeranalysis.notes.occurrences.viewer ke akun.

Untuk menetapkan izin:

Buat file JSON yang berisi informasi yang diperlukan untuk menetapkan kebijakan IAM di catatan Anda:

cat > /tmp/iam_request.json << EOM
{
  'resource': '${NOTE_URI}',
  'policy': {
    'bindings': [
      {
        'role': 'roles/containeranalysis.notes.occurrences.viewer',
        'members': [
          'serviceAccount:${ATTESTOR_SERVICE_ACCOUNT}'
        ]
      }
    ]
  }
}
EOM

Tambahkan akun layanan dan peran akses yang diminta ke kebijakan IAM untuk catatan yang Anda buat:
```
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"
```
Jika Anda menambahkan peran ke kebijakan menggunakan metode di atas, peran tersebut akan menggantikan peran yang ada di catatan. Jika ingin mempertahankan peran yang sudah ada, pastikan Anda menyertakannya dalam data JSON saat menetapkan kebijakan.

Menyiapkan kunci kriptografis

Dengan Otorisasi Biner, Anda dapat menggunakan kunci PKIX untuk memverifikasi identitas penandatangan yang membuat pengesahan dengan aman. Hal ini memastikan bahwa hanya pihak terverifikasi yang dapat mengizinkan image container. Sebagai alternatif untuk PKIX, Anda juga dapat menggunakan kunci PGP.

Membuat pasangan kunci PKIX

Dengan Otorisasi Biner, Anda dapat menggunakan pasangan kunci PKIX asimetris untuk memverifikasi pengesahan. Pasangan kunci terdiri dari kunci pribadi, yang digunakan signer untuk menandatangani pengesahan secara digital, dan kunci publik yang Anda tambahkan ke attestor. Kemudian, pemberlakuan Otorisasi Biner menggunakan kunci publik di attestor untuk memverifikasi bahwa pengesahan dibuat oleh penanda tangan.

Dalam panduan ini, Elliptic Curve Digital Signing Algorithm (ECDSA) yang direkomendasikan digunakan untuk menghasilkan pasangan kunci PKIX. Anda juga dapat menggunakan kunci RSA atau PGP untuk penandatanganan. Lihat Tujuan dan algoritma utama untuk informasi selengkapnya tentang algoritma penandatanganan.

Pasangan kunci asimetris yang dihasilkan dan disimpan di Cloud KMS sesuai dengan format PKIX. Untuk membuat kunci Cloud KMS yang akan digunakan dengan Otorisasi Biner, lihat Membuat Kunci Asimetris. Pastikan Anda memilih Asymmetric Sign sebagai tujuan kunci saat membuat kunci.

PKIX (Cloud KMS)

Untuk membuat pasangan kunci di Cloud KMS, lakukan langkah berikut:

Untuk menyiapkan variabel lingkungan yang diperlukan guna membuat pasangan kunci, jalankan perintah berikut:
```
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
```
Ganti kode berikut:
- KMS_KEY_PROJECT_ID: ID project tempat kunci disimpan.
- KMS_KEY_LOCATION: lokasi kunci
- KMS_KEYRING_NAME: nama key ring
- KMS_KEY_NAME: nama kunci
- KMS_KEY_VERSION: versi kunci
- KMS_KEY_ALGORITHM: algoritma; ec-sign-p256-sha256 direkomendasikan
- KMS_PROTECTION_LEVEL: tingkat perlindungan—misalnya, software

Untuk membuat keyring, jalankan perintah berikut:

gcloud kms keyrings create ${KMS_KEYRING_NAME} \
    --location ${KMS_KEY_LOCATION}

Untuk membuat kunci, jalankan perintah berikut:

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 (kunci lokal)

Untuk menghasilkan pasangan kunci PKIX asimetris lokal baru dan menyimpannya dalam file:

Buat kunci:

PRIVATE_KEY_FILE="/tmp/ec_private.pem"
openssl ecparam -genkey -name prime256v1 -noout -out ${PRIVATE_KEY_FILE}

Karena file ini berisi kunci publik dan pribadi, Anda perlu mengekstrak kunci publik ke file terpisah agar dapat menambahkannya ke attestor:
```
PUBLIC_KEY_FILE="/tmp/ec_public.pem"
openssl ec -in ${PRIVATE_KEY_FILE} -pubout -out ${PUBLIC_KEY_FILE}
```

Membuat attestor

Langkah berikutnya adalah membuat attestor itu sendiri dalam Otorisasi Biner dengan catatan Artifact Analysis terkait. Anda juga harus menambahkan kunci publik kriptografis.

Untuk membuat attestor:

Siapkan variabel lingkungan untuk menyimpan nama attestor seperti yang ditentukan dalam Otorisasi Biner:
```
ATTESTOR_NAME=ATTESTOR_NAME
```
dengan ATTESTOR_NAME adalah nama attestor yang ingin Anda buat (misalnya, build-secure atau prod-qa).

Buat attestor dan lampirkan kunci keamanan publik:

PKIX (Cloud KMS)

Siapkan variabel lingkungan tambahan untuk menyimpan informasi tentang pasangan kunci Cloud KMS untuk panggilan ke Binary Authorization API.

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

Download file kunci publik dari Cloud KMS dan simpan ke file bernama /tmp/kms_public_key.pem di sistem lokal Anda.

Buat file JSON yang berisi informasi yang diperlukan untuk membuat attestor:

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

Buat attestor:

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 (kunci lokal)

Buat file JSON yang berisi informasi yang diperlukan untuk membuat attestor:

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

Buat attestor:

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

Tambahkan binding peran IAM untuk project deploy ke attestor. Hal ini digunakan oleh Otorisasi Biner saat mengevaluasi kebijakan untuk menentukan apakah project memiliki izin untuk mengakses attestor yang direferensikan.

Buat file JSON yang berisi informasi yang diperlukan untuk menetapkan kebijakan IAM pada attestor Anda:

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

Tambahkan akun layanan dan peran akses yang diminta ke kebijakan IAM untuk catatan yang Anda buat:

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"

Memverifikasi bahwa attestor telah dibuat

Untuk memverifikasi bahwa attestor sudah dibuat, jalankan perintah berikut:

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

Langkah selanjutnya

Membuat pengesahan