Abstract
The OCI (Open Container Initiative) specification has expanded well beyond container images. OCI 1.1 introduced the referrers API, a standard mechanism for attaching arbitrary artifacts to any OCI manifest by digest. This enables a supply chain pattern that is gaining adoption across the CNCF ecosystem: store provenance attestations, SBOMs, vulnerability scan results, and signatures as OCI artifacts in the same registry as the image they describe, linked by digest rather than by convention. The tooling - Cosign, ORAS, Notation, and the OCI Registry-as-Storage (ORAS) project - is converging around this model, but the operational details of managing referrer chains in production registries are not yet well documented.
The Referrers API and How Attestations Are Stored
An OCI referrer is an artifact manifest whose subject field points to another manifest by digest. When a CI pipeline signs an image with Cosign, it creates a signature artifact manifest with subject set to the image digest, then pushes it to the registry. Cosign stores the signature in a special tag format (sha256-<digest>.sig) for registries that do not implement the referrers API, and falls back to the standard referrers endpoint when the registry supports it. The ORAS CLI’s oras discover command lists all referrers attached to an artifact digest, giving operators a single command to audit the full attestation chain for any image in the registry. Harbor, Quay, and Amazon ECR added referrers API support at different points in 2024-2025; teams using older registry versions need to check which fallback storage mechanism Cosign and Notation use, because policy verification tooling behavior differs between the two.
Signing with Notation and the TUF Trust Model
The Notary Project’s notation CLI is the CNCF alternative to Cosign for signing OCI artifacts. Notation uses X.509 certificates and a pluggable key provider (Azure Key Vault, AWS KMS, or HashiCorp Vault via plugins) rather than Sigstore’s keyless OIDC model. The trust model is based on TUF (The Update Framework): trust policies defined in ~/.config/notation/trustpolicy.json specify which certificate chains are trusted to sign artifacts from which registries and repositories. This is more explicit than Sigstore’s transparency-log-based model and fits organizations that already operate a PKI and want signing authority to flow from existing certificate hierarchies. Notation’s notation verify command enforces these policies at pull time, and Ratify - a Kubernetes external data provider for Gatekeeper - integrates Notation’s verification into Kubernetes admission control so unsigned or untrusted images are rejected before the kubelet pulls them.
Registry Garbage Collection and Referrer Retention
Attaching attestations as referrers creates a retention dependency: deleting the subject image should cascade to delete its referrers, and garbage collection must be aware of the referrer graph to avoid orphaning signatures. Most enterprise registries handle this correctly as of their 2024-2025 releases, but self-hosted distributions (like CNCF Distribution’s registry image) require explicit garbage collection configuration to walk the referrer graph. Teams running air-gapped registries should verify that their GC policy retains referrers for at least as long as the subject image, and should test GC behavior against a staging registry before enabling automated collection in production. A missing signature for an image that policy requires to be signed will block deployments; an orphaned signature for a deleted image is benign but clutters the referrer listing and wastes storage.