使用 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 中创建备注,以存储证明流程中使用的可信元数据。
  • 设置一个可用于验证证明者身份的 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"
    

多项目使用

如果将证明者存储在一个项目中,之后又在另一个单独的项目中对其进行部署,则必须将 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(本地密钥)

如需生成新的本地非对称 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-secureprod-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}"

后续步骤