Announcing the Open Container InitiativeReferrers API on Quay.io: A step towards enhanced security and compliance

To help enhance IT security and compliance, we are announcing the availability of the Open Container Initiative (OCI) Referrers API on Quay.io. This new feature aligns with our recent improvements in OCI content discovery compliance, helping Quay.io meet current OCI standards. The introduction of the Referrers API is a significant advancement that enables better artifact management and supports secure software supply chain practices.

Why is this relevant?

As software supply chain attacks have surged, establishing provenance for container images has become increasingly critical. The OCI Referrers API allows users to associate artifacts—such as signatures and Software Bill of Materials (SBOMs)—with existing OCI images in a more organized way. Instead of relying on tag naming conventions, the API introduces a structured graph that links these artifacts directly to their associated images.

This new approach to content discovery makes the management of artifacts much more straightforward, as all related data can be easily accessed through a relationship graph, rather than relying on an overburdened tag namespace.

This capability is particularly beneficial for free and open source software (FOSS) projects and any organization adopting secure software supply chain best practices. By using the OCI Referrers API, you can demonstrate the integrity of software in a verifiable and transparent way, verifying the provenance of the associated images and the artifacts.

How does the Referrers API work?

At a high level, the OCI Referrers API allows users to query for all artifacts associated with a specific image digest. By using the following endpoint users can retrieve a list of all related manifests, including signatures and SBOMs. Each artifact can be referenced without creating additional tags, providing a streamlined way to manage dependencies and maintain clarity in your registry.

GET /v2/<name>/referrers/<digest>?artifactType=<artifactType>

Key benefits of OCI Referrers API:

Improved artifact management

The OCI Referrers API enhances structured organization, discoverability and lifecycle management by making sure that related artifacts—such as signatures and SBOMs—are copied, archived or deleted alongside main images. This helps prevent orphaned artifacts in registries and helps maintain overall integrity and traceability, which facilitates compliance with security protocols.

Enhanced security and verification

The API can significantly improve security by simplifying access to artifact verification. Users can more easily query and retrieve signatures associated with images, streamlining the verification process necessary for improving deployment security. This helps security-conscious organizations implement stronger security measures in their software supply chain and streamlines the  pre-deployment verification process, so only trusted images are used in production environments.

Efficient content promotion

As part of the OCI 1.1 specifications, the Referrers API adopts a standard approach to artifact management, improving interoperability between different tools, ecosystems and platforms. It also enables the transfer of main images with related artifacts that are copied together in a single operation. This reduces the number of API calls required to transfer all relevant metadata and security information from point A to point B. This is especially beneficial for organizations managing complex deployments across registries who are looking to enhance operational efficiency. Overall, this streamlined process is essential for modern cloud-native environments.

What the OCI Referrers API enables

The introduction of the OCI Referrers API unlocks several use cases, especially when integrated with tools like Cosign from the SigStore project. One such use case is: Cosign allows users to sign images and attach SBOMs without generating extra tags for these artifacts, keeping your tag namespace clean while making sure that critical security information is readily accessible.

This is what a registry with auto generated tags looks like
With the Referrers API one would essentially not see the tags starting with sha256-:

Rather than relying on auto-generated tags for each artifact, the Referrers API enables direct linking of artifacts to images. This simplifies content management and discovery, allowing organizations to maintain a clean and structured registry while providing faster access to critical security information and metadata.

These associations are visualized in a content graph, which allows the Referrers API to support a more streamlined and organized approach to managing and distributing content across the container ecosystem.

Example use case: Signing images with Cosign

One compelling use case involves using Cosign to sign images and attach multiple SBOMs, enhancing security and compliance. Here's how to use Cosign with the OCI Referrers API:

Artifact types

The type of an artifact may be determined from the artifactType property introduced in the OCI 1.1 specification. If artifactType is not defined, the configuration's mediaType property can be used to determine the type of the artifact.

Reference types

OCI 1.1 introduces the concept reference types and allows the linking of artifacts. The subject property is used to refer to the target of a reference. This can be used to create associations between artifacts, such as signatures, SBOM, Open Policy Agent (OPA) bundles, etc.

An advantage of the OCI Referrers API, especially when paired with Cosign, is its ability to establish associations between artifacts like signatures and SBOMs through a content graph.

Now, we will go through the process of pushing, assigning and attaching

This new system provides a standardized way to manage and verify the relationships between container images and their associated metadata, enhancing security and traceability in the software supply chain.

Step-by-step process

1. Push base image: Push a basic image using podman

   podman push quay.io/devtable/ubi:9.2-755.1697625012

   This pushes the base image to the registry.

2. Sign SBOM: Sign the SBOM for the image:

   cosign sign-blob ubi9-9.2-755.1697625012.json --output-signature ubi9-9.2-755.1697625012.sig

   This creates a signature for the SBOM file.

3. Attach SBOM to image

   oras attach --distribution-spec v1.1-referrers-api --artifact-type sbom/example quay.io/devtable/ubi:9.2-755.1697625012 ubi9-9.2-755.1697625012.json

   Oras is a generic client, also providing libraries to push and pull OCI artifacts to OCI registries.
   This step attaches the SBOM to the image using the new Referrers API.

4. Attach SBOM signature

   oras attach --distribution-spec v1.1-referrers-api --artifact-type sbom-sig/example quay.io/devtable/ubi@sha256:42647b7132330f710f32b5097938d13d87ea1d44dcc06b74a875b554dbd0481f ubi9-9.2-755.1697625012.sig

   This attaches the SBOM's signature to the SBOM itself.

5. Sign image

   cosign sign --registry-referrers-mode=oci-1-1 quay.io/devtable/ubi:9.2-755.1697625012

   This command signs the image using Cosign, utilizing the OCI 1.1 Referrers mode.

Verification

After completing these steps, you can use oras discover to check the references of each image/artifact, verifying that the SBOM and signatures were correctly attached:

bash

$ oras discover --distribution-spec v1.1-referrers-api quay.io/devtable/ubi:9.2-755.1697625012

This command will return results indicating how many artifacts reference your image:

text

Discovered 2 artifacts referencing 9.2-755.1697625012
Digest: sha256:f0dd2af8846cd91547719233ccedae4e3042398d427b3046be138b208dc7254a
Artifact Type   Digest
sbom/example    sha256:42647b7132330f710f32b5097938d13d87ea1d44dcc06b74a875b554dbd0481f
                sha256:0226a8a5153f0df477be5c586c81cc94933a9dfc76c7a59ea31c939263949103

You can further query for specific artifacts, such as SBOM signatures:

bash

$ oras discover --distribution-spec v1.1-referrers-api quay.io/devtable/ubi@sha256:42647b7132330f710f32b5097938d13d87ea1d44dcc06b74a875b554dbd0481f

This command will yield:

text

Discovered 1 artifact referencing sha256:42647b7132330f710f32b5097938d13d87ea1d44dcc06b74a875b554dbd0481f
Digest: sha256:42647b7132330f710f32b5097938d13d87ea1d44dcc06b74a875b554dbd0481f
Artifact Type      Digest
sbom-sig/example   sha256:6812313c8798a76ad06478de3440d04111649f4cd57a9dc36d7d8413f80f8615

Query for referrers

After signing and attaching artifacts, you can also use the Referrers API to query for all related artifacts:

bash

curl -H "Authorization: Bearer <your-token>" https://quay.io/v2/<namespace>/<repo>/referrers/<digest>?artifactType=<artifactType> " https://quay.io/v2///referrers/?artifactType=

Review results

The API will return a list of all referrer artifacts, including signatures and SBOMs, allowing you to verify the integrity of your images without cluttering the tag namespace.

Example: Tag decluttering benefit

With auto-generated tags, a registry might look cluttered with tags starting with sha256-. However, with the Referrers API, users can avoid this clutter by linking artifacts directly to images.

Conclusion

The addition of the OCI Referrers API on Quay.io marks a significant advancement in our ongoing commitment to enhancing security and compliance within the container ecosystem. By enabling better artifact management and supporting secure software supply chain practices, we help developers and organizations establish  verifiable provenance for their software.

As always, we welcome your feedback! Please reach out via email (quay-sig@googlegroups.com). Your input is invaluable as we strive to improve Quay’s product experience with your needs in mind.

Additional resources

For further reading, check out the following resources:

1. Official OCI Spec
2. Open Containers Distribution Spec
3. SigStore Quickstart Guide