本頁面由 Cloud Translation API 翻譯而成。

使用 REST API 建立驗證者

本頁說明如何使用 REST API，在 Binary Authorization 中建立自訂簽署者。

您也可以使用 Google Cloud CLI 或 Google Cloud 控制台執行這些步驟。這項工作是設定二進位授權流程的一部分。

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

總覽

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

建立驗證者時，您必須執行下列操作：

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

在單一專案設定中，您會在設定二進位授權政策的同一個 Google Cloud 專案中建立驗證者。在多專案設定中，您很可能會有部署者專案 (用於設定政策) 和驗證者專案 (用於儲存驗證者)。

事前準備

設定預設專案

如果尚未設定預設 Google Cloud 專案，請設定：

PROJECT_ID=PROJECT_ID
gcloud config set project ${PROJECT_ID}

設定環境

設定環境變數，儲存專案名稱和編號：

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

如果驗證者和部署者專案是同一個專案，請為這兩個變數使用相同的專案 ID。

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

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"

建立構件分析附註

二進位授權會使用構件分析功能，儲存授權程序中使用的可信中繼資料。您建立的每個認證者都必須建立一個構件分析記事。每項認證都會儲存為這則附註的例項。

如要建立構件分析記事：

設定環境變數，儲存記事 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)。

在文字編輯器中，建立 JSON 檔案，說明構件分析附註：/tmp/note_payload.json

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

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

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

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

設定記事的權限

您也必須在建立的 Artifact Analysis 附註中設定權限，讓驗證者專案服務帳戶可以存取。方法是更新記事的 IAM 政策，將 containeranalysis.notes.occurrences.viewer 角色指派給帳戶。

如何設定權限：

產生 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

將服務帳戶和要求的存取角色新增至您建立的記事 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"

設定加密編譯金鑰

二進位授權可讓您使用 PKIX 金鑰，安全地驗證建立認證的簽署者身分。確保只有經過驗證的當事人可以授權容器映像檔。除了 PKIX，您也可以使用 PGP 金鑰。

建立 PKIX 金鑰組

您可以使用非對稱式 PKIX 金鑰組，透過二進位授權驗證認證。金鑰組包含私密金鑰 (簽署者用來以數位方式簽署認證) 和公開金鑰 (您新增至認證者)。稍後，二進位授權執行者會使用驗證者中的公開金鑰，驗證簽署者是否建立了認證。

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

在 Cloud KMS 中產生及儲存的非對稱金鑰配對符合 PKIX 格式。如要建立 Cloud KMS 金鑰以搭配使用二進位授權，請參閱建立非對稱金鑰。建立金鑰時，請務必選擇「非對稱式簽署」做為金鑰用途。

PKIX (Cloud KMS)

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

如要設定建立金鑰組所需的環境變數，請執行下列指令：
```
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

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

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

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

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 (本機金鑰)

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

產生金鑰：

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

由於這個檔案同時包含公開和私密金鑰，您必須將公開金鑰擷取到個別檔案，才能新增至驗證者：
```
PUBLIC_KEY_FILE="/tmp/ec_public.pem"
openssl ec -in ${PRIVATE_KEY_FILE} -pubout -out ${PUBLIC_KEY_FILE}
```

建立驗證者

下一步是在二進位授權中建立驗證者本身，並附上相關的構件分析附註。您也必須新增加密公開金鑰。

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

設定環境變數，儲存在 Binary Authorization 中定義的驗證者名稱：
```
ATTESTOR_NAME=ATTESTOR_NAME
```
其中 ATTESTOR_NAME 是要建立的認證者名稱 (例如 build-secure 或 prod-qa)。

建立驗證者並附加公開安全金鑰：

PKIX (Cloud KMS)

設定其他環境變數，儲存呼叫 Binary Authorization API 時使用的 Cloud KMS 金鑰配對相關資訊。

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

從 Cloud KMS 下載公開金鑰檔案，並儲存至本機系統中名為 /tmp/kms_public_key.pem 的檔案。

產生 JSON 檔案，其中包含建立認證者所需的資訊：

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

建立驗證者：

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 (本機金鑰)

產生 JSON 檔案，其中包含建立認證者所需的資訊：

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

建立驗證者：

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

為部署者專案新增至驗證者的 IAM 角色繫結。二進位授權評估政策時，會使用這項資訊判斷專案是否有權存取參照的驗證者。

產生 JSON 檔案，其中包含在驗證者上設定 IAM 政策所需的資訊：

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

將服務帳戶和要求的存取角色新增至您建立的記事 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://binaryauthorization.googleapis.com/v1beta1/projects/${ATTESTOR_PROJECT_ID}/attestors/${ATTESTOR_NAME}:setIamPolicy"

確認驗證者已建立

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

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

後續步驟

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

使用 REST API 建立驗證者 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

總覽

事前準備

設定預設專案

設定環境

建立構件分析附註

設定記事的權限

設定加密編譯金鑰

建立 PKIX 金鑰組

PKIX (Cloud KMS)

PKIX (本機金鑰)

建立驗證者

PKIX (Cloud KMS)

PKIX (本機金鑰)

確認驗證者已建立

後續步驟

使用 REST API 建立驗證者