使用 gcloud CLI 创建证明者

本页面介绍如何使用 Google Cloud CLI 在 Binary Authorization 中创建证明者。作为替代方案，您还可以使用 Google Cloud 控制台或 REST API 来执行这些步骤。这个任务是设置 Binary Authorization 的一部分。

Cloud Build 用户：您可以改用 built-by-cloud-build 证明者仅部署由 Cloud Build 构建的映像。

证明者是一种 Google Cloud 资源，供 Binary Authorization 用于验证证明。如需详细了解证明，请参阅 Binary Authorization 概览。

如需创建证明者，请执行以下操作：

• 在 Artifact Analysis 中创建备注，以存储证明流程中使用的可信元数据。
• 设置一个可用于验证证明者身份的公钥基础架构 (X.509) (PKIX) 密钥对。（Cloud Key Management Service [Cloud KMS] 生成的非对称密钥对采用与 PKIX 兼容的格式。）
• 在 Binary Authorization 中创建证明者本身，并将您创建的备注与公钥相关联。

在单项目设置中，您可以在配置了 Binary Authorization 政策的那个 Google Cloud 项目中创建证明者。如需查看包含这些步骤的端到端单项目教程，请参阅 Google Cloud CLI 使用入门或 Google Cloud 控制台使用入门。

在多项目设置中，我们建议您拥有单独的项目：一个部署者项目（在其中配置政策）：一个证明者项目（在其中存储证明者）和一个证明项目（用于证明）。如需查看包含这些步骤的端到端多项目教程，请参阅多项目设置。

准备工作

在创建证明者之前，请执行以下操作：

1. 启用 Binary Authorization。

2. 为您的平台设置 Binary Authorization。

设置项目环境

在本部分中，您将设置环境变量。

设置环境变量以存储项目名称和编号： 如果您的证明者项目和部署者项目是同一项目，请对这两个变量使用同一项目 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 备注

Binary Authorization 使用 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 << EOM
   {
     "name": "${NOTE_URI}",
     "attestation": {
       "hint": {
         "human_readable_name": "${DESCRIPTION}"
       }
     }
   }
   EOM
   

3. 通过向 Artifact Analysis REST API 发送 HTTP 请求来创建备注：

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

设置针对备注的 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 角色授予与证明者上的部署者项目关联的服务账号。

设置加密密钥

借助 Binary Authorization，您可以使用 PKIX 密钥来验证证明。

生成密钥对

在本指南中，您将使用推荐的椭圆曲线数字签名算法 (ECDSA) 生成 PKIX 密钥对。您也可以使用 RSA 或 PGP 密钥对。如需详细了解如何对算法签名，请参阅密钥用途和算法。

PKIX 密钥对包含一个签名者用于对证明签名的私钥，以及一个添加到证明者的公钥。在部署时，Binary Authorization 会使用此公钥来验证证明。

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. 设置环境变量，以存储 Binary Authorization 中指定的证明者的名称：

   ATTESTOR_NAME=ATTESTOR_NAME
   

   其中，ATTESTOR_NAME 是您要创建的证明者的名称（例如 build-secure 或 prod-qa）。

2. 在 Binary Authorization 中创建证明者资源：

   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 角色绑定。Binary Authorization 在评估政策以确定项目是否有权访问任何关联证明时，会用到此角色绑定。

   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 更新 Binary Authorization 政策以要求提供证明。