If a registry has no OCI referrers API, how does a client still discover an image's signatures?
answer
- 404 does not mean nothing is there
- the digest becomes a tag name
- colon becomes a dash
- who builds the index changed hands
- read-modify-write loses a racing entry
basics
~20 sIt falls back to a derived tag. When the referrers endpoint returns 404, the client reads a tag formed from the subject digest, of the shape sha256-<hex>, in the same repository; that tag points to an index listing the referring manifests.
solid answer
~50 sThe OCI distribution spec defines a fallback so trust material still works on registries that predate the referrers API. Discovery is keyed on the digest either way. If `GET /v2/<repo>/referrers/<digest>` returns 404, the client instead resolves a tag derived from the digest by replacing the colon with a dash — `sha256-<hex>` — in the same repository. That tag holds an ordinary image index whose entries are the referring manifests. The important difference is who maintains it: with the API the registry builds the index from the `subject` fields it sees, so it is always consistent. With the fallback, *clients* maintain it — push a referrer, then read-modify-write that tag. That makes it racy under concurrent pushes, deletable by anyone with push access, and — critically — a separate object that a copy or replication step may or may not carry. The two discovery paths can therefore disagree about whether a digest has trust material at all.
go deeper
Know that discovery has two routes — an endpoint keyed on the digest and, on older registries, a tag whose name is derived from that digest — and that both live in the same repository as the artifact.
Explain the fallback mechanically: 404 triggers it, the colon becomes a dash, the tag points at an index, and clients rather than the registry keep that index current.
Bring the operational consequences: races that lose an entry, a mutable tag anyone with push access can delete, and copy steps that carry one discovery path but not the other.
Decide the estate-wide rule — which registries must support the API before they are allowed in a verified path, and whether you tolerate two discovery mechanisms or standardise on one and accept the migration cost.
## Two paths to the same answer Discovery of trust material is keyed on the digest of the thing being vouched for. The OCI distribution spec offers two ways to run that lookup, and a conforming client tries them in order. **Path one — the referrers API.** `GET /v2/<repository>/referrers/<digest>` returns an image index listing every manifest in that repository whose `subject` descriptor is the given digest. The registry derives this index itself: when a manifest carrying a `subject` is pushed, the registry records the back-edge. Nobody has to maintain anything, and there is no way for two concurrent pushes to clobber each other's entry. **Path two — the fallback tag.** A registry that does not implement the endpoint answers 404. The client then falls back to a tag whose name is derived mechanically from the subject digest: take `sha256:abcd…`, replace the colon with a dash, and resolve the tag `sha256-abcd…` in the same repository. That tag points at an ordinary image index, and its entries are the referring manifests. Same shape of answer, different mechanism for producing it. ## Why the difference bites The fallback moves index maintenance from the registry to the client, and that is where the operational sharp edges come from. **It is a read-modify-write.** To attach a second referrer — say a signature exists and you now push an attestation — the client must fetch the current index, add an entry, and push the tag again. Two jobs doing that concurrently against the same subject can each read the pre-existing index and each write back a version containing only their own addition. The loser's entry is silently gone: the artifact was pushed and stored, but it is no longer discoverable. **It is a tag, so it is mutable and writable.** Anyone with push access to the repository can overwrite or delete that tag. Deleting it does not delete the signature manifests; it deletes the only way to find them. Under the API path there is no equivalent single object to remove. **It is an extra object in the repository.** This is the one that produces confusing incidents. A copy or replication step that walks *tags* will happily carry `sha256-abcd…` along with everything else, because it looks like an ordinary tag — but a step that copies a specific image by digest will not, because nothing in the image points at it. Conversely, a copy tool that understands the referrers graph will carry the referring manifests but may not recreate the fallback tag on the destination. ## When the two paths disagree Picture a vendor's public artifact being promoted into a customer's internal registry by a replication job. The destination registry does implement the referrers API. Two failure shapes: - The job walked tags, so `sha256-abcd…` arrived and points at manifests that were *not* copied, or that were copied without their `subject` field surviving a media-type rewrite. The fallback tag lists referrers the registry cannot serve; the API says there are none. A client that prefers the API sees an unsigned artifact. - The job walked the referrers graph, so the signature manifests arrived with their `subject` intact and the destination registry indexed them — but the fallback tag was never recreated. Now the API answers correctly and any older client, or any client talking to a *third* hop without the API, sees nothing. Both are transport bugs that present as policy failures. The tell is always the same: the image digest is identical on both sides, so the artifact is provably the same bytes, and only the discoverability differs. ## What a careful client and a careful operator do A client should try the API first, treat a 404 as "not implemented" rather than "no referrers", fall back to the derived tag, and filter the resulting index by artifact type itself — the API accepts a filter parameter but a registry may ignore it and return everything. An operator should know which of the two paths every registry in the estate supports, and make promotion steps explicitly referrer-aware rather than assuming that copying an image copies what vouches for it. It is also worth knowing that referring manifests are untagged objects: a registry policy that garbage-collects untagged manifests can reap trust material while leaving the image perfectly intact — the fallback tag, ironically, is sometimes the only thing keeping them anchored.
- Why is a 404 from the referrers endpoint ambiguous, and how should a client handle it?A 404 means the registry does not implement the endpoint, not that the digest has no referrers — a registry that does implement it returns an empty index instead. Treating 404 as "unsigned" would fail verification against every older registry. The correct behaviour is to fall back to the derived `sha256-<hex>` tag and only conclude there is no trust material once that lookup also comes back empty or absent.
- Two CI jobs attach an attestation to the same image at the same time on a registry without the referrers API. What can go wrong?Both read the current fallback index, both add their own entry, both push the tag. The second push wins and its index omits the first job's entry. The first artifact is still stored in the registry and is still valid, but nothing can find it, so verification behaves as though it was never produced. Serialising attachment per subject, or using a registry with the API, removes the race.
- Does the fallback tag hold the signature itself?No. It holds an index — a list of descriptors pointing at the referring manifests, each of which holds the actual payload blob. That indirection is why the tag and the manifests can get separated during a copy: they are distinct objects, and a step can move one without the other.
saying these in an interview costs you the question
- Reads a 404 from the referrers endpoint as proof nothing is signed
- Thinks the derived tag stores the signature itself
- Assumes the registry maintains the fallback index
- Ignores that concurrent attachments can clobber the fallback tag