feat: add OCI 1.1 Referrers API support with configurable distribution #1691
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,179 @@ | ||
| <!-- | ||
| --- | ||
| linkTitle: "OCI Artifact Distribution (Referrers)" | ||
| weight: 35 | ||
| --- | ||
| --> | ||
|
|
||
| # OCI Artifact Distribution: the Referrers Schema | ||
|
|
||
| When Chains signs an image, it has to put the signature and the attestation | ||
| somewhere. Both are stored in the same registry as the image. This page explains | ||
| the two ways Chains can do that, and how to turn on the newer one. | ||
|
|
||
| If you don't change anything, Chains uses the older tag-based layout and just | ||
| works. Read on if you want to use the OCI 1.1 Referrers API instead. | ||
|
|
||
| ## The problem with the old layout | ||
|
|
||
| cosign, which Chains uses under the hood, has always stored a signature by | ||
| pushing an extra tag next to the image. For an image at digest `sha256:abc...`, | ||
| it creates tags like `sha256-abc....sig` and `sha256-abc....att`. | ||
|
|
||
| This works on every registry, but it isn't ideal: | ||
|
|
||
| - The registry fills up with extra tags that aren't real images. | ||
| - These tags are easy to confuse with actual image tags. | ||
| - No OCI standard describes this layout, so every tool has to special-case it. | ||
|
|
||
| ## What the Referrers schema is | ||
|
|
||
| The [OCI 1.1 distribution spec](https://github.com/opencontainers/distribution-spec/blob/v1.1.0/spec.md#listing-referrers) | ||
| added a standard way to attach one artifact to another. Instead of inventing a | ||
| tag, you push the signature or attestation as its own manifest that records the | ||
| image it belongs to in a `subject` field. The registry can then answer a simple | ||
| question: "what artifacts refer to this image?" | ||
|
|
||
| This is the **Referrers schema**. The payoff is no extra tags, a clean registry, | ||
| and a standard that registries and policy tools already understand. | ||
|
|
||
| ## How cosign enables it | ||
|
|
||
| cosign (and the `go-containerregistry` library it uses) already speaks the | ||
| Referrers schema. If the registry supports the Referrers API natively, cosign | ||
| uses it. If it doesn't, cosign falls back to the spec's **referrers tag schema**: | ||
|
Comment on lines
+43
to
+44
Contributor
There was a problem hiding this comment. This isn't necessarily the case. I don't think cosign would have used the referrer's API in v2 unless an additional option was passed. But maybe you have tested things more than me, so your content might be more authoritative. |
||
| it keeps a single `sha256-<digest>` index tag and uses it to track referrers. | ||
|
|
||
| Either way it is still "referrers mode" — the content is the same, no `.sig` or | ||
| `.att` tags are created, and `cosign verify` and `oras discover` both work. This | ||
|
Contributor
There was a problem hiding this comment. Another issue is that the .att points to a manifest referencing all of the attestations. This does not have a stable digest. If some other process pushes additional attestations, I think they will all be added into this one manifest. By moving attestations to use the referrer's API, each attestation will have its own image manifest and will therefore have a stable digest. This was one of the primary motivators why I wanted to change. |
||
| fallback is automatic and needs no configuration, so it covers registries that | ||
| don't yet have native support. | ||
|
|
||
| ## How Chains enables it | ||
|
|
||
| Chains exposes this through a single config flag in the `chains-config` | ||
| ConfigMap: | ||
|
|
||
| ```yaml | ||
| apiVersion: v1 | ||
| kind: ConfigMap | ||
| metadata: | ||
| name: chains-config | ||
| namespace: tekton-chains | ||
| data: | ||
| storage.oci.distribution-method: "referrers-api" | ||
| ``` | ||
|
|
||
| | Value | What Chains does | | ||
| |---|---| | ||
| | `legacy` (default) | Old tag-based layout (`.sig` / `.att` tags), DSSE-encoded. Works everywhere. | | ||
| | `referrers-api` | OCI 1.1 Referrers schema. No extra tags, with automatic fallback on registries that lack native support. | | ||
|
|
||
| That's the only knob. You pick *where* artifacts go, and Chains picks the right | ||
| encoding to match (explained next). | ||
|
|
||
| > [!NOTE] | ||
| > This flag only takes effect when the OCI storage backend is in use — that is, | ||
| > when `artifacts.oci.storage`, `artifacts.taskrun.storage`, or | ||
| > `artifacts.pipelinerun.storage` includes `oci`. If you store signatures and | ||
| > attestations somewhere else (for example Tekton results, a docstore, or | ||
| > Grafeas), `storage.oci.distribution-method` has no effect. | ||
|
|
||
| > [!TIP] | ||
| > The cosign bundled with Chains is new enough for everything described here, so | ||
| > you don't need to install anything or pass extra flags. | ||
|
Comment on lines
+82
to
+84
|
||
|
|
||
| ## Why referrers + protobuf, and not referrers + DSSE | ||
|
|
||
| There is one subtlety worth understanding: the *encoding* of the payload. | ||
|
|
||
| - In **legacy** mode, the attestation is a **DSSE** envelope. This is what cosign | ||
| has always written and what existing tooling verifies. | ||
| - In **referrers** mode, Chains writes the attestation as a **Sigstore protobuf | ||
| bundle**. | ||
|
Comment on lines
+90
to
+93
Contributor
There was a problem hiding this comment. Maybe you want to differentiate by what is the default configuration for cosign versions? |
||
|
|
||
| You might expect a third option — referrers with DSSE — but it's a dead end in | ||
| practice. cosign's verification for referrer-stored attestations expects the | ||
| protobuf bundle, not a DSSE envelope. A DSSE-over-referrers attestation can be | ||
| written, but `cosign verify-attestation` won't reliably verify it. The industry | ||
| is also moving toward the protobuf bundle as the standard format. | ||
|
|
||
| So Chains keeps it simple: legacy means DSSE, referrers means protobuf. The two | ||
| are tied together on purpose — it avoids a confusing matrix of combinations, | ||
| some of which no tool can actually verify. If a genuine need for a separate | ||
| encoding option ever appears, it can be added later without changing this flag. | ||
|
Comment on lines
+95
to
+104
Contributor
There was a problem hiding this comment. Can we just simplify this to state that we maintain support with cosign which doesn't support referrer's without protobuf? |
||
|
|
||
| Image **signatures** are not affected by this. In referrers mode they use | ||
| cosign's native signature manifest — the exact thing `cosign verify` looks for — | ||
| so signature verification works with no extra flags. | ||
|
Comment on lines
+106
to
+108
Contributor
There was a problem hiding this comment. I thought the referring signatures were stored as protobuf as well. |
||
|
|
||
| ## Verifying | ||
|
|
||
| Verification is the same in both modes — point cosign at your key: | ||
|
|
||
| ```shell | ||
| # Verify a signature | ||
| cosign verify \ | ||
| --key k8s://tekton-chains/signing-secrets \ | ||
| <image>@sha256:<digest> | ||
|
|
||
| # Verify an attestation | ||
| cosign verify-attestation \ | ||
| --key k8s://tekton-chains/signing-secrets \ | ||
| --type slsaprovenance \ | ||
| <image>@sha256:<digest> | ||
| ``` | ||
|
|
||
| To see what was stored, use [`oras`](https://oras.land/): | ||
|
|
||
| ```shell | ||
| oras discover <image>@sha256:<digest> | ||
| ``` | ||
|
|
||
| ## Things to keep in mind in referrers mode | ||
|
|
||
| These are interoperability notes, not bugs in Chains. | ||
|
|
||
| 1. **`storage.oci.repository` is ignored.** A referrer has to live next to the | ||
|
|
||
| image it points at, so the override that redirects storage elsewhere doesn't | ||
| apply. Chains logs a warning and stores the referrer next to the image. The | ||
| override still works in `legacy` mode. | ||
|
|
||
| 2. **cosign's `--experimental-oci11` discovery may not find the attestation.** | ||
| Chains stores it as a protobuf bundle; that older discovery path filters on a | ||
| different type. The attestation is still there — `oras discover` shows it and | ||
| policy engines can use it — and `cosign verify` of the signature is | ||
| unaffected. | ||
|
Comment on lines
+142
to
+146
Contributor
There was a problem hiding this comment. Is there cosign documentation that we can point to? I don't think that this option exists for all versions of cosign (i.e. protobuf is the default for newer cosign versions, so I wouldn't expect it to be there). |
||
|
|
||
| 3. **Some registries accept a write but don't return it on read.** If a registry | ||
| reports success but you can't read the referrer back, it isn't fully OCI 1.1 | ||
| compliant. Switch that registry to `legacy`. | ||
|
|
||
| 4. **`oras discover` may show a different `artifactType` per registry.** This is | ||
| display only; the stored content and verification don't change. | ||
|
|
||
| 5. **Concurrent writes can race on fallback registries.** Without the native API, | ||
| the index tag is updated with read-append-write, so simultaneous writes to the | ||
| same image can drop an entry. A registry with the native Referrers API avoids | ||
| this. | ||
|
Comment on lines
+155
to
+158
Contributor
There was a problem hiding this comment. This refers just to the legacy mode? |
||
|
|
||
| ## Registry compatibility | ||
|
|
||
| cosign works with a wide range of registries, including AWS ECR, GCP Artifact | ||
| Registry, Docker Hub, Azure Container Registry, JFrog Artifactory, GitLab and | ||
| GitHub Container Registries, Harbor, and Quay. See the | ||
|
Comment on lines
+162
to
+164
|
||
| [cosign registry support page](https://docs.sigstore.dev/cosign/system_config/registry_support/) | ||
| for the current list. | ||
|
|
||
| | Registry | `legacy` | `referrers-api` | | ||
| |---|---|---| | ||
| | GCR, ECR, Artifact Registry, quay.io | ✓ | ✓ (native Referrers API) | | ||
| | GHCR (`ghcr.io`) | ✓ | ✓ (native API not exposed; cosign uses the tag-schema fallback) | | ||
| | Any other OCI registry | ✓ | ✓ (native API if available, otherwise tag-schema fallback) | | ||
|
Comment on lines
+168
to
+172
Contributor
There was a problem hiding this comment. This table is confusing. I was expecting that it was trying to say which ones had support for the actual referrer's API but you are just saying waht is compatible? I feel like this shouldn't be included so that you are not expected to keep it up to daet. |
||
|
|
||
| ## See also | ||
|
|
||
| - [Chains configuration reference](config.md) — all `storage.oci.*` keys. | ||
| - [Signing](signing.md) — how signing keys and secrets are configured. | ||
| - [cosign registry support](https://docs.sigstore.dev/cosign/system_config/registry_support/) | ||
| - [OCI distribution spec — Listing Referrers](https://github.com/opencontainers/distribution-spec/blob/v1.1.0/spec.md#listing-referrers) | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
nit: This is only an issue if you expect everything to be a pullable container image. If you expect that the registry is an OCI registry, it isn't necessarily an issue. But even with that, it muddies the purpose of a content that is stored in a registry and is referenceable by tags. The supporting metadata can get confused with the top level artifacts themselves. Maybe that is what you were saying below?