镜像证明存储

Buildkit 支持为构建工件创建和附加证明。这些证明可以提供构建过程中的有价值信息，包括但不限于：软件物料清单（SBOMs）， SLSA 来源证明，构建日志等。

本文档描述了当前用于存储证明的自定义格式，该格式旨在与当前的注册表实现兼容。未来，我们可能会支持将证明导出为其他格式。

证明存储在镜像索引中的清单对象中，类似于OCI artifacts。

属性

断言清单

断言清单附在根镜像索引对象下，位于一个单独的 OCI 镜像清单。每个断言清单可以包含多个断言 blob，清单中的所有断言都适用于一个平台清单。标准 OCI 和 Docker 清单的所有属性仍然适用。

镜像 config 描述符将指向一个有效的镜像配置, 但是，它不包含有关声明的详细信息，应予以忽略，因为它只是为了兼容性而包含的。

每个镜像层在 layers 中将包含一个描述符，用于单个证明 blob。每个层的 mediaType 将根据其内容进行设置，内容之一为：

application/vnd.in-toto+json（目前唯一支持的选项）
表示一个 in-toto 证明 blob

任何未知的mediaType应被忽略。

为了协助证明遍历，可以在每个层描述符上设置以下注释：

in-toto.io/predicate-type
此注解将在包含的证明为 in-toto 证明时设置（目前唯一支持的选项）。注解将被设置为包含与证明内部的 predicateType 属性相同的值。
当存在时，此注解可用于查找要查找的具体签名，以避免拉取其他签名的内容。

断言 Blob

每一层的内容将是一个依赖于其mediaType的 blob。

application/vnd.in-toto+json

该 blob 内容将包含完整的 in-toto 验证声明：

{
  "_type": "https://in-toto.io/Statement/v0.1",
  "subject": [
    {
      "name": "<NAME>",
      "digest": {"<ALGORITHM>": "<HEX_VALUE>"}
    },
    ...
  ],
  "predicateType": "<URI>",
  "predicate": { ... }
}

证明的主题应设置为目标清单的相同摘要，该清单在证明清单描述符中描述，或其中的某个对象。

Attestation Manifest Descriptor

Attestation manifests are attached to the root image index, in the manifests key, after all the original runnable manifests. All properties of standard OCI and Docker manifest descriptors continue to apply.

为防止容器运行时意外地拉取或运行清单中描述的镜像，将设置 attestation 清单的 platform 属性为 unknown/unknown，如下所示：

"platform": {
  "architecture": "unknown",
  "os": "unknown"
}

为了协助索引遍历，将在清单描述符描述符上设置以下注释：

vnd.docker.reference.type
此注释描述了工件的类型，并将被设置为attestation-manifest。如果指定了任何其他值，则应忽略整个清单。
vnd.docker.reference.digest
此注解将包含镜像索引中对象的摘要，该摘要由 attestation manifest 引用。
当存在时，此注解可用于查找与选定的镜像清单匹配的证明清单。

示例

展示与 linux/amd64 镜像关联的软件物料清单（SBOM）签名示例

镜像索引（`sha256:94acc2ca70c40f3f6291681f37ce9c767e3d251ce01c7e4e9b98ccf148c26260`）：

此镜像索引定义了两个描述符：一个AMD64镜像sha256:23678f31..和该镜像的sha256:02cb9aa7..个证明清单。

{
  "mediaType": "application/vnd.oci.image.index.v1+json",
  "schemaVersion": 2,
  "manifests": [
    {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "digest": "sha256:23678f31b3b3586c4fb318aecfe64a96a1f0916ba8faf9b2be2abee63fa9e827",
      "size": 1234,
      "platform": {
        "architecture": "amd64",
        "os": "linux"
      }
    },
    {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "digest": "sha256:02cb9aa7600e73fcf41ee9f0f19cc03122b2d8be43d41ce4b21335118f5dd943",
      "size": 1234,
      "annotations": {
        "vnd.docker.reference.digest": "sha256:23678f31b3b3586c4fb318aecfe64a96a1f0916ba8faf9b2be2abee63fa9e827",
        "vnd.docker.reference.type": "attestation-manifest"
      },
      "platform": {
         "architecture": "unknown",
         "os": "unknown"
      }
    }
  ]
}

Attestation manifest (`sha256:02cb9aa7600e73fcf41ee9f0f19cc03122b2d8be43d41ce4b21335118f5dd943`)：

此 attestation 清单包含一个 attestation，该 attestation 是一个 in-toto attestation，其中包含“https://spdx.dev/Document”谓词，表示它正在为该镜像定义一个 SBOM。

{
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "schemaVersion": 2,
  "config": {
    "mediaType": "application/vnd.oci.image.config.v1+json",
    "digest": "sha256:a781560066f20ec9c28f2115a95a886e5e71c7c7aa9d8fd680678498b82f3ea3",
    "size": 123
  },
  "layers": [
    {
      "mediaType": "application/vnd.in-toto+json",
      "digest": "sha256:133ae3f9bcc385295b66c2d83b28c25a9f294ce20954d5cf922dda860429734a",
      "size": 1234,
      "annotations": {
        "in-toto.io/predicate-type": "https://spdx.dev/Document"
      }
    }
  ]
}

镜像配置（`sha256:a781560066f20ec9c28f2115a95a886e5e71c7c7aa9d8fd680678498b82f3ea3`）：

{
  "architecture": "unknown",
  "os": "unknown",
  "config": {},
  "rootfs": {
    "type": "layers",
    "diff_ids": [
      "sha256:133ae3f9bcc385295b66c2d83b28c25a9f294ce20954d5cf922dda860429734a"
    ]
  }
}

Layer 内容 (`sha256:1ea07d5e55eb47ad0e6bbfa2ec180fb580974411e623814e519064c88f022f5c`)：

包含SBOM数据的证明主体，以SPDX格式列出构建过程中使用的软件包。

{
  "_type": "https://in-toto.io/Statement/v0.1",
  "predicateType": "https://spdx.dev/Document",
  "subject": [
    {
      "name": "_",
      "digest": {
        "sha256": "23678f31b3b3586c4fb318aecfe64a96a1f0916ba8faf9b2be2abee63fa9e827"
      }
    }
  ],
  "predicate": {
    "SPDXID": "SPDXRef-DOCUMENT",
    "spdxVersion": "SPDX-2.2",
    ...