使用 REST API 创建证明者

本页面介绍了如何使用 REST API 在 Binary Authorization 中创建自定义证明者。

作为替代方案，您还可以使用 Google Cloud CLI 或 Google Cloud 控制台来执行这些步骤。此任务是设置 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 兼容的格式。）您也可以使用 PGP 密钥对，而非 PKIX 密钥。
  • 在 Binary Authorization 中创建证明者本身，并将您创建的备注与公钥相关联。

在单项目设置中，您可以在配置了 Binary Authorization 政策的那个 Google Cloud 项目中创建证明者。在多项目设置中，您很可能有一个部署者项目，其中配置了您的政策；还有一个单独的证明者项目，用于存储证明者。

准备工作

  1. 启用 Binary Authorization。

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

设置默认项目

设置默认 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"

创建 Artifact Analysis 备注

Binary Authorization 使用 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. 在文本编辑器中，在 /tmp/note_payload.json 中创建一个 JSON 文件，用于描述 Artifact Analysis 备注：

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

设置针对备注的权限

您还必须设置针对您创建的 Artifact Analysis 备注的权限，以便证明者项目服务账号可以访问该备注。为此，请更新该备注的 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"

设置加密密钥

借助 Binary Authorization，您可以使用 PKIX 密钥安全地验证创建了证明的签名者的身份。这样可以确保只有经过验证的各方才能对容器映像进行授权。作为 PKIX 的替代方案，您还可以使用 PGP 密钥。

创建 PKIX 密钥对

借助 Binary Authorization，您可以使用非对称 PKIX 密钥对来验证证明。密钥对包含一个私钥（供签名者用于对证明进行数字签名）和一个公钥（您会将其添加到证明者）。之后，Binary Authorization Enforcer 会使用证明者的公钥来验证签名者是否已创建证明。

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

在 Cloud KMS 中生成和存储的非对称密钥对符合 PKIX 格式的要求。如需创建 Cloud KMS 密钥以用于 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}

PKIX（本地密钥）

如需生成新的本地非对称 PKIX 密钥对并将其存储在文件中，请执行以下操作：

  1. 生成密钥：

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

  2. 由于此文件既包含公钥，又包含私钥，因此您需要将公钥提取到单独的文件中，以便将其添加到证明者中：

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

创建证明者

下一步是在 Binary Authorization 中使用关联的 Artifact Analysis 备注创建证明者本身。您还必须添加加密公钥。

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

  1. 设置环境变量，以存储 Binary Authorization 中指定的证明者的名称：

    ATTESTOR_NAME=ATTESTOR_NAME

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

  2. 创建证明者并附加安全公钥：

    PKIX (Cloud KMS)

    1. 设置其他环境变量，以存储有关用于调用 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}"

    2. 从 Cloud KMS 下载公钥文件，并将其保存到本地系统上名为 /tmp/kms_public_key.pem 的文件中。

    3. 生成一个包含创建证明者所需的信息的 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

    4. 创建证明者：

      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（本地密钥）

    1. 生成一个包含创建证明者所需的信息的 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

    2. 创建证明者：

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

  3. 为证明者添加部署者项目的 IAM 角色绑定。Binary Authorization 在评估政策以确定项目是否有权访问引用的证明者时，会用到此角色绑定。

    生成一个 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/"

后续步骤