使用 gcloud CLI 创建证明者

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

证明者是一种 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 控制台使用入门。

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

准备工作

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

必须启用 Binary Authorization。如需了解操作方法，请参阅启用 Binary Authorization。
必须将政策配置为仅允许通过证明者验证的映像。如需了解操作方法，请参阅使用 gcloud CLI 配置政策。

设置项目环境

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

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

如需创建备注，请运行以下命令：

设置环境变量以存储备注 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 文件：

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

通过向 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 角色。

如需添加角色，请执行以下操作：

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

多项目使用

如果将证明者存储在一个项目中，之后又在另一个单独的项目中对其进行部署，则必须将 roles/binaryauthorization.attestorsVerifier 角色授予与证明者上的部署者项目关联的服务账号。

设置加密密钥

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

生成密钥对

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

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

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}
```
请替换以下内容：
- 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 密钥对并将其存储在文件中，请执行以下操作：

生成私钥：

PRIVATE_KEY_FILE 是包含用于对证明载荷签名的私钥的那个文件的名称。

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

从私钥中提取公钥并将其存储在一个文件中：

PUBLIC_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）。

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

为证明者添加部署者项目的 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

如需将公钥添加到证明者，请执行以下操作：
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}"

使用 gcloud CLI 创建证明者

准备工作

设置项目环境

创建 Artifact Analysis 备注

设置针对备注的 IAM 权限

多项目使用

设置加密密钥

生成密钥对

PKIX (Cloud KMS)

PKIX（本地密钥）

创建证明者

PKIX (Cloud KMS)

PKIX（本地密钥）

保存公钥 ID

验证证明者是否已创建

后续步骤