When a container image is signed, where is the signature stored and how does a verifier find it?
answer
- signing must not change what you pinned
- trust material lives beside, not inside
- the small manifest points up at the image
- reverse lookup keyed on repository plus digest
- pulling the image never fetches it
basics
~20 sA signature is stored beside the image, not inside it: a separate manifest in the same repository whose subject field names the image digest. A verifier asks the registry which artifacts refer to that digest.
solid answer
~50 sSigning does not modify the image, so the image digest is unchanged and the signature cannot live inside it. Instead the signature is pushed as its own small manifest into the *same repository*, and that manifest carries a `subject` field holding the digest of the image it is about. Discovery is therefore digest-keyed: given `sha256:abc...`, a verifier calls the registry's referrers endpoint for that repository and digest and gets back an index of every manifest whose subject is that digest — signatures, attestations, SBOM attachments. Two consequences matter in practice. First, discovery is scoped to a repository: the same image copied to another repository has the same digest but no referrers there until they are copied too. Second, pulling the image never pulls its trust material; verification is a separate lookup you have to make deliberately.
go deeper
Be ready to say plainly that the signature is a separate object in the same repository that points at the image digest, and that pulling the image does not pull it.
Explain the subject field and the reverse lookup it enables, and why the lookup is scoped to a repository even though a digest is globally unique.
Show that you treat verification as an extra round trip that any hop in the distribution path can silently break, and that discovery is not the same as acceptance.
Own the consequence: if trust material is a separate graph, every promotion, mirror and export path in the estate is a place where verifiability can be lost, and that has to be designed for rather than discovered in an outage.
## The problem discovery solves A container image is addressed by the digest of its manifest — a hash over the bytes. That is what makes a digest a good name: it cannot be re-aimed. But it also means a signature *cannot* be added to the image, because adding anything would change the bytes and therefore change the digest, and the thing you signed would no longer be the thing you pull. So trust material has to live somewhere else, and the verifier needs a rule for finding it. The answer the OCI ecosystem settled on is: **store it beside the subject, keyed on the subject's digest.** ## What actually gets pushed When a tool signs an image it uploads a second, tiny manifest to the *same repository*. That manifest has: - a small payload blob (the signature, or a signed attestation document), - an `artifactType` saying what kind of thing it is, - a `subject` field containing the descriptor — media type, digest, size — of the image being signed. The `subject` field is the whole mechanism. It turns a flat pile of manifests in a repository into a graph: leaf objects point *up* at what they are about. Nothing in the image points *down* at its signature, because the image is immutable. ## How a verifier walks that graph The OCI distribution spec exposes the reverse edge as the **referrers API**: a request of the shape `GET /v2/<repository>/referrers/<digest>`. The registry answers with an image index listing every manifest it holds whose `subject` is that digest, each entry carrying its `artifactType` so a client can pick out signatures from SBOM attachments from provenance. The API accepts an artifact-type filter, but a registry is free to ignore it and return everything, so a careful client filters the returned index itself rather than assuming the server did. A verifier's flow is therefore: 1. Resolve what you are about to run to a digest (from a tag, or better, pinned already). 2. Ask the registry for the referrers of that digest, in that repository. 3. Pull the candidate signature manifests and their payload blobs. 4. Check each signature cryptographically against the image digest, and check that the identity behind it is one your policy accepts. Step 4 is the one people skip. Steps 1–3 are *discovery* — a lookup. They tell you an object exists; they tell you nothing about whether you should trust it. ## Three properties that surprise people **Signing does not change the image digest.** A signed image and an unsigned image are byte-identical. "Is this image signed?" is not a question you can answer by looking at the image; it is a question about what else the registry holds. **Discovery is repository-scoped.** The digest is a global name, but the referrers lookup is `repository + digest`. Copy the image manifest and its layers into a different repository — a regional registry, an internal promotion target, a customer's registry — and the digest is identical while the referrers are simply absent. The image verifies as the same bytes and fails verification for lack of trust material, which reads like a policy bug and is actually a transport bug. **Pulling never pulls trust material.** A normal image pull walks manifest → config → layers. It never touches the referrers endpoint. Verification is an extra, explicit round trip, and anything in the path that only understands "an image is a manifest plus its blobs" — an export to a tarball, a mirror that caches what was requested, a copy tool that walks tags — moves the image perfectly and leaves the signature behind. ## Why the design is still right Storing trust material as ordinary registry objects means it inherits the registry's storage, authentication, replication and content-addressing for free, and means an artifact can accumulate new attestations over its life — a signature at build time, a scan result a week later, an approval after a review — without ever disturbing the artifact everyone has already pinned. The cost is that "the artifact" is now a graph rather than a blob, and every hop in your distribution path has to know that.
- If signing does not change the image digest, how can two teams disagree about whether the same digest is signed?Because signedness is not a property of the bytes. It is a property of what a particular repository, on a particular registry, happens to hold alongside that digest. One team queries a registry where the referrers were pushed and sees a signature; the other queries a copy of the repository where only the image travelled and sees nothing. Same digest, different answer, and both lookups are behaving correctly.
- Can an artifact have more than one signature, and what should a verifier do with several?Yes — the referrers index for a digest can list many manifests: signatures from different signers, an SBOM attachment, provenance, a later scan result. A verifier should treat the list as candidates, filter by artifact type, and require at least one that both validates cryptographically and comes from an identity its policy names. More referrers is not stronger evidence, and the absence of any is a policy decision, not a technical one.
Think of a sealed evidence bag with its own barcode. You cannot write on the bag without breaking the seal, so the sign-offs are filed separately in the same drawer, each one quoting the barcode. Move the bag to another drawer and the sign-offs stay behind.
saying these in an interview costs you the question
- Says the signature is embedded in the image manifest
- Thinks signing produces a new image digest
- Assumes a normal image pull also fetches the signature
- Believes a digest is enough to find trust material anywhere