使用 gcloud CLI 建立驗證者

本頁說明如何使用 Google Cloud CLI 在二進位授權中建立驗證者。您也可以使用 Google Cloud 控制台或 REST API 執行這些步驟。這項工作是設定二進位授權的一部分。

Cloud Build 使用者：您可以改用built-by-cloud-build驗證者，只部署 Cloud Build 建構的映像檔。

「驗證者」是Google Cloud 資源，二進位授權會使用驗證者驗證「認證」。如要進一步瞭解認證，請參閱「二進位授權總覽」。

如要建立驗證者，請執行下列操作：

• 在「Artifact Analysis」中建立附註，儲存認證程序中使用的可信中繼資料。
• 設定可用於驗證驗證者身分的公用金鑰基礎架構 (X.509) (PKIX) 金鑰組。(由 Cloud Key Management Service (Cloud KMS) 產生的非對稱金鑰配對採用 PKIX 相容格式)。
• 在二進位授權中建立驗證者，並將您建立的附註和公開金鑰建立關聯。

在單一專案設定中，您會在設定二進位授權政策的相同 Google Cloud專案中建立驗證者。如需包含這些步驟的單一專案端對端教學課程，請參閱「開始使用 Google Cloud CLI」或「開始使用 Google Cloud 控制台」。

在多專案設定中，建議您使用不同的專案：部署者專案 (用於設定政策)、驗證者專案 (用於儲存驗證者)，以及驗證專案 (用於驗證)。如需包含這些步驟的端對端多專案教學課程，請參閱多專案設定。

事前準備

建立認證者之前，請先完成下列步驟：

1. 啟用二進位授權。

2. 為平台設定二進位授權。

設定專案環境

在本節中，您將設定環境變數。

設定環境變數，儲存專案名稱和編號。如果驗證者和部署者專案是同一個專案，請為這兩個變數使用相同的專案 ID。

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

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

您也必須取得專案的服務帳戶名稱：

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"

建立 Artifact Analysis 附註

二進位授權會使用Artifact Analysis功能，儲存授權程序中使用的可信中繼資料。您建立的每個驗證者都必須建立一份 Artifact Analysis 附註。每項驗證都會儲存為這則附註的出現。

如要建立附註，請按照下列步驟操作：

1. 設定環境變數，儲存記事 ID 和易於解讀的說明：

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

   更改下列內容：

   • NOTE_ID：記事的內部名稱，由英數字元組成，不得包含空格，例如 test-attestor-note
   • NOTE_URI：記事資源的完整路徑
   • DESCRIPTION：使用者可辨識的附註顯示名稱，例如 Test Attestor Note

2. 建立描述附註的 JSON 檔案：

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

3. 如要建立附註，請將 HTTP 要求傳送至 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}"
   

   注意：二進位授權不支援構件分析區域儲存空間或區域端點。建議使用 Artifact Analysis 全球 API 端點 (https://containeranalysis.googleapis.com/)。

   如要確認記事是否已順利建立，請執行下列指令：

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

設定附註的 IAM 權限

您必須在 Artifact Analysis 附註資源上，為驗證者專案服務帳戶授予 Identity and Access Management (IAM) 角色。方法是將驗證者專案服務帳戶新增至附註 IAM 政策的 containeranalysis.notes.occurrences.viewer 角色。

如要新增角色，請按照下列步驟操作：

1. 產生 JSON 檔案，其中包含在記事上設定 IAM 角色所需的資訊：

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

2. 將服務帳戶和要求的存取角色新增至您建立的記事 IAM 政策：

   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"
   

   注意： 使用上述方法在政策中新增角色時，系統會取代記事上所有現有角色。如要保留現有角色，請務必將這些角色納入上述 JSON 資料檔案。

多專案使用

如果您將驗證者儲存在一個專案中，並部署在另一個專案中，則必須在驗證者上，將 roles/binaryauthorization.attestorsVerifier 角色授予與部署者專案相關聯的服務帳戶。

設定加密編譯金鑰

二進位授權可讓您使用 PKIX 金鑰驗證認證。

產生金鑰組

在本指南中，您會使用建議的橢圓曲線數位簽章演算法 (ECDSA)，產生 PKIX 金鑰組。您也可以使用 RSA 或 PGP 金鑰組。 如要進一步瞭解簽署演算法，請參閱「金鑰用途與演算法」一文。

PKIX 金鑰組包含私密金鑰 (簽署者用來簽署證明) 和公開金鑰 (您新增至證明者)。部署時，二進位授權會使用這個公開金鑰驗證證明。

PKIX (Cloud KMS)

如要在 Cloud KMS 中建立金鑰組，請按照下列步驟操作：

1. 如要設定建立金鑰組所需的環境變數，請執行下列指令：

   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
   

   更改下列內容：

   • KMS_KEY_PROJECT_ID：儲存金鑰的專案 ID
   • KMS_KEY_LOCATION：金鑰的位置
   • KMS_KEYRING_NAME：金鑰環名稱
   • KMS_KEY_NAME：金鑰名稱
   • KMS_KEY_VERSION：金鑰版本
   • KMS_KEY_ALGORITHM：演算法； 建議使用 ec-sign-p256-sha256
   • KMS_PROTECTION_LEVEL：防護等級，例如 software

2. 如要建立金鑰環，請執行下列指令：

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

3. 如要建立金鑰，請執行下列指令：

   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}
   

   更改下列內容：

   • KMS_KEY_NAME：金鑰名稱
   • KMS_KEY_LOCATION：金鑰的位置
   • KMS_KEYRING_NAME：金鑰環名稱
   • KMS_KEY_PURPOSE：金鑰用途，設為 ASYMMETRIC_SIGN
   • KMS_KEY_ALGORITHM：建議使用此演算法。ec-sign-p256-sha256
   • KMS_PROTECTION_LEVEL：防護等級，例如 software

PKIX (本機金鑰)

警告：我們強烈建議不要在正式環境中使用本機產生的金鑰配對，因為這會造成安全風險。建議改用 Cloud Key Management Service。這個範例僅供說明之用。

如要產生新的本機非對稱 PKIX 金鑰組並儲存在檔案中，請執行下列操作：

1. 產生私密金鑰：

   PRIVATE_KEY_FILE 是包含私密金鑰的檔案名稱，用於簽署認證酬載。

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

2. 從私密金鑰中擷取公開金鑰，並儲存在檔案中：

   PUBLIC_KEY_FILE 是包含儲存在驗證者中的公開金鑰的檔案名稱。

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

建立驗證者

如要建立驗證者，請按照下列步驟操作：

1. 設定環境變數，儲存在二進位授權中定義的驗證者名稱：

   ATTESTOR_NAME=ATTESTOR_NAME
   

   其中 ATTESTOR_NAME 是您要建立的驗證者名稱 (例如 build-secure 或 prod-qa)。

2. 在二進位授權中建立驗證者資源：

   gcloud --project="${ATTESTOR_PROJECT_ID}" \
       container binauthz attestors create "${ATTESTOR_NAME}" \
       --attestation-authority-note="${NOTE_ID}" \
       --attestation-authority-note-project="${ATTESTOR_PROJECT_ID}"
   

3. 為部署者專案新增至驗證者的 IAM 角色繫結。二進位授權評估政策時，會使用這項設定判斷專案是否有權存取任何相關聯的認證。

   gcloud container binauthz attestors add-iam-policy-binding \
       "projects/${ATTESTOR_PROJECT_ID}/attestors/${ATTESTOR_NAME}" \
       --member="serviceAccount:${DEPLOYER_SERVICE_ACCOUNT}" \
       --role=roles/binaryauthorization.attestorsVerifier
   

4. 如要將公開金鑰新增至驗證者，請按照下列步驟操作：

   PKIX (Cloud KMS)

   如要將 Cloud KMS 金鑰組中的公開金鑰新增至驗證者，請執行下列指令：

   gcloud --project="${ATTESTOR_PROJECT_ID}" \
       container binauthz attestors public-keys add \
       --attestor="${ATTESTOR_NAME}" \
       --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}"
   

   PKIX (本機金鑰)

   如要將本機儲存的 PKIX 公開金鑰新增至驗證者，請執行下列指令：

   gcloud --project="${ATTESTOR_PROJECT_ID}" \
       container binauthz attestors public-keys add \
       --attestor="${ATTESTOR_NAME}" \
       --pkix-public-key-file=${PUBLIC_KEY_FILE} \
       --pkix-public-key-algorithm=ecdsa-p256-sha256
   

   如果您將公開金鑰新增至驗證者，但未指定金鑰 ID (可以是任何字串)，系統會自動以 RFC 6920 格式指派金鑰 ID：ni:///sha-256;...，其中 ... 是公開金鑰的編碼雜湊。這個值會傳回至指令輸出的 id 欄位。傳回的 ID 可以儲存在 PUBLIC_KEY_ID 中，並用於建立認證。

儲存公開金鑰 ID

如要建立驗證，您需要公開金鑰 ID。

如要儲存公開金鑰 ID，請從上述 binauthz attestors public-keys add 指令的輸出內容複製。

或者，您也可以隨時使用下列指令查看驗證者的公開金鑰 ID：

gcloud container binauthz attestors describe ${ATTESTOR}。

如要將公開金鑰 ID 儲存在環境變數中，請輸入下列指令：

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

確認驗證者已建立

如要確認驗證者已建立，請執行下列指令：

gcloud container binauthz attestors list \
    --project="${ATTESTOR_PROJECT_ID}"

後續步驟

• 瞭解如何為驗證者建立驗證。
• 使用Google Cloud 控制台、Google Cloud CLI 和 REST API，更新二進位授權政策，要求提供認證。