📚 课程目录第2章 OCI分发规范基础

2. OCI 分发规范基础：OCI Image Spec、Distribution Spec、Artifact Manifest 核心概念

在构建镜像供应链信任体系之前，必须理解 OCI（Open Container Initiative）分发规范的核心组成。Sigstore 的集成、镜像签名、分发验证等所有操作都建立在 OCI 规范之上。本章聚焦三个核心规范：Image Spec（镜像规范）、Distribution Spec（分发规范）和 Artifact Manifest（制品清单），并阐明它们如何构成信任边界的基础层。

2.1 OCI Image Spec：镜像的标准化描述

OCI Image Spec 定义了容器镜像的标准格式，确保不同工具（如 Docker、Podman、containerd）能够一致地构建、存储和运行镜像。其核心是 Manifest（清单）与 Config（配置）的分离架构。

  关键设计原则： 镜像内容由内容可寻址存储（Content-Addressable Storage, CAS）管理，每个层（Layer）和配置通过其哈希值（Digest）唯一标识，不可篡改。

组件	作用	示例字段
Manifest	描述镜像的元数据，引用 Config 和 Layers	`schemaVersion`, `mediaType`, `config`, `layers`
Config	包含镜像运行时配置（环境变量、入口点等）	`architecture`, `os`, `rootfs`, `history`
Layer	文件系统变更集，通过 DiffID 和 ChainID 关联	`mediaType`, `size`, `digest`
Index	多架构镜像的入口点，引用多个 Manifest	`manifests`, `annotations`

// OCI Image Manifest 示例（JSON 结构）
{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "config": {
    "mediaType": "application/vnd.oci.image.config.v1+json",
    "size": 7023,
    "digest": "sha256:b5b2b2c507a0944348e0303114d8d93aaaa081732b86451d9bce1f432a537bc7"
  },
  "layers": [
    {
      "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip",
      "size": 32654,
      "digest": "sha256:9834876dcfb05cb167a5c24953eba58c4ac89b1adf57f28f2f9d09af107ee8f0"
    }
  ],
  "annotations": {
    "org.opencontainers.image.created": "2025-01-15T10:00:00Z"
  }
}

信任边界关联： Sigstore 的签名对象正是 Manifest 的 Digest。一旦 Manifest 被篡改，Digest 变化，签名验证立即失败。这是镜像供应链防篡改的第一道防线。

2.2 OCI Distribution Spec：镜像的标准化分发

OCI Distribution Spec 定义了客户端与镜像仓库之间的 HTTP API 交互协议，涵盖镜像的推送（Push）、拉取（Pull）、删除（Delete）和发现（Discovery）。该规范确保不同仓库实现（如 Harbor、Docker Hub、Quay）遵循统一接口。

核心 API 端点包括：

Blob 操作： GET /v2/{name}/blobs/{digest} — 拉取层或配置数据
Manifest 操作： PUT /v2/{name}/manifests/{reference} — 上传 Manifest（Tag 或 Digest）
标签操作： GET /v2/{name}/tags/list — 列出仓库所有标签
目录操作： GET /v2/_catalog — 列出仓库所有镜像仓库

// 拉取 Manifest 的 HTTP 请求示例
GET /v2/my-app/manifests/latest HTTP/1.1
Host: registry.example.com
Accept: application/vnd.oci.image.manifest.v1+json

// 响应头包含 Digest
Docker-Content-Digest: sha256:abc123...

安全注意事项： 分发规范本身不提供传输层加密以外的安全机制。镜像的完整性验证（如签名校验）必须由上层工具（如 Sigstore、Notary）实现。Distribution Spec 仅保证“如何传输”，不保证“传输的内容是否可信”。

2.3 Artifact Manifest：扩展信任边界的关键

OCI Artifact Manifest 是 OCI 规范在 1.1 版本中引入的重要扩展，允许在镜像仓库中存储非容器镜像的制品（Artifact），例如：软件物料清单（SBOM）、签名文件、漏洞扫描报告、策略文件等。Artifact Manifest 与 Image Manifest 结构相似，但 mediaType 不同，且 Config 字段可以为空或指向自定义配置。

特性	Image Manifest	Artifact Manifest
用途	描述容器镜像	描述任意制品（签名、SBOM、报告）
mediaType	`application/vnd.oci.image.manifest.v1+json`	`application/vnd.oci.artifact.manifest.v1+json`
Config 要求	必须包含 Config 对象	Config 可选，可为空
引用方式	通过 Tag 或 Digest 引用	通过 `subject` 字段引用关联的镜像
信任价值	镜像内容完整性	将信任元数据（签名、策略）与镜像绑定

// OCI Artifact Manifest 示例（引用签名制品）
{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.artifact.manifest.v1+json",
  "artifactType": "application/vnd.dev.cosign.artifact.sig.v1+json",
  "blobs": [
    {
      "mediaType": "application/octet-stream",
      "size": 238,
      "digest": "sha256:xyz789..."
    }
  ],
  "subject": {
    "mediaType": "application/vnd.oci.image.manifest.v1+json",
    "size": 1024,
    "digest": "sha256:abc123..."
  },
  "annotations": {
    "org.opencontainers.image.created": "2025-01-15T12:00:00Z"
  }
}

  信任边界扩展： Artifact Manifest 的 subject 字段将签名、SBOM 等信任元数据直接绑定到目标镜像的 Digest 上。Sigstore 的 Cosign 工具正是利用这一机制，将签名作为 Artifact 推送到镜像仓库，实现“镜像 + 签名”的原子化存储与分发。

2.4 三层规范的关系与信任边界

下图展示了 OCI Image Spec、Distribution Spec 和 Artifact Manifest 在镜像供应链中的协作关系，以及它们如何共同构成信任边界的基础层。

2.5 核心概念对比与选型建议

概念	核心作用	信任边界贡献	Sigstore 集成点
Image Spec	镜像标准化描述	Digest 防篡改	签名对象（Manifest Digest）
Distribution Spec	镜像标准化分发	传输层完整性	API 扩展（Referrers API）
Artifact Manifest	制品标准化存储	信任元数据绑定	签名/SBOM 存储载体

实践建议： 在构建镜像供应链信任体系时，优先确保仓库支持 OCI Artifact Manifest（OCI 1.1+）。这是 Sigstore Cosign 将签名与镜像原子化存储的前提。如果仓库仅支持 Image Spec，签名将无法通过 subject 字段关联，需要额外的索引机制。

2.6 本章小结

OCI Image Spec 提供了镜像内容的标准化结构与完整性指纹（Digest）。
OCI Distribution Spec 定义了镜像的标准化分发协议，确保跨仓库互操作性。
OCI Artifact Manifest 扩展了仓库的存储能力，使签名、SBOM 等信任元数据能够与镜像绑定。
三层规范共同构成了镜像供应链信任边界的基础设施层，为 Sigstore 等签名工具提供了可操作的标准化环境。