OCI and Referrers

Cosign supports the OCI 1.1 specification, which introduces the referrers API for discovering artifacts associated with a container image. This page explains how cosign uses the referrers API and how to configure signature and attestation storage modes.

What is the Referrers API? #

The OCI Distribution Specification 1.1 introduced the referrers API as a standardized way to discover artifacts (like signatures, attestations, and SBOMs) associated with a container image.

Instead of relying on tag naming conventions (e.g., sha256-<digest>.sig), the referrers API uses a subject field in the artifact manifest to create a direct relationship between the artifact and the image it references. Registries that support OCI 1.1 expose a /referrers/<digest> endpoint that returns all artifacts linked to a given image digest.

Valid Format and Storage Combinations #

Cosign supports different combinations of bundle format and OCI storage mode. Not all combinations are valid:

Key Constraints #

1. New bundle format requires OCI 1.1: The new bundle format (--new-bundle-format=true, default in cosign 3.0+) always uses the OCI 1.1 referrers API. It cannot use tag-based storage.

2. Old format requires disabling signing config: When using --new-bundle-format=false, you must also set --use-signing-config=false. The default TUF-based signing config requires the new bundle format.

3. Old format attestations always use tags: When using --new-bundle-format=false, attestations are always stored using tag-based storage, regardless of any --registry-referrers-mode flag.

4. Registry support required: If your registry does not support OCI 1.1, you must use --new-bundle-format=false with tag-based storage.

Scenario 1: Old Format + Tag-based (OCI 1.0) #

Use this mode with registries that don’t support OCI 1.1.

Signing #

# With key-based signing (uploads to Rekor transparency log)
cosign sign --key cosign.key \
  --new-bundle-format=false \
  --use-signing-config=false \
  $IMAGE

# With keyless signing
cosign sign \
  --new-bundle-format=false \
  --use-signing-config=false \
  $IMAGE

The signature is stored at a tag: sha256-<digest>.sig

Verification #

# Key-based verification
cosign verify --key cosign.pub \
  --new-bundle-format=false \
  $IMAGE

# Keyless verification
cosign verify \
  --new-bundle-format=false \
  --certificate-identity=name@example.com \
  --certificate-oidc-issuer=https://accounts.example.com \
  $IMAGE

Attestations #

# Create attestation (uploads to Rekor)
cosign attest \
  --key cosign.key \
  --new-bundle-format=false \
  --use-signing-config=false \
  --type slsaprovenance \
  --predicate predicate.json \
  $IMAGE

# Verify attestation
cosign verify-attestation \
  --key cosign.pub \
  --new-bundle-format=false \
  --type slsaprovenance \
  $IMAGE

The attestation is stored at a tag: sha256-<digest>.att

Scenario 2: Old Format + OCI 1.1 Referrers (Signatures Only) #

This mode stores signatures using the OCI 1.1 referrers API while using the old bundle format. Note that attestations are not supported with OCI 1.1 in this mode, they will fall back to tag-based storage.

Signing #

# Requires COSIGN_EXPERIMENTAL=1 environment variable
COSIGN_EXPERIMENTAL=1 cosign sign \
  --key cosign.key \
  --new-bundle-format=false \
  --use-signing-config=false \
  --registry-referrers-mode=oci-1-1 \
  $IMAGE

The signature is stored as an OCI 1.1 referrer (discoverable via /referrers/<digest> endpoint).

Verification #

cosign verify \
  --key cosign.pub \
  --new-bundle-format=false \
  --experimental-oci11=true \
  $IMAGE

Important: The --experimental-oci11 flag is required for verification to discover signatures stored via the referrers API.

Scenario 3: New Format + OCI 1.1 Referrers (Default) #

This is the default mode in cosign 3.0+. Both signatures and attestations are stored using the OCI 1.1 referrers API.

Signing #

# Key-based signing
cosign sign --key cosign.key $IMAGE

# Keyless signing (default)
cosign sign $IMAGE

The signature is stored as an OCI 1.1 referrer with the new sigstore bundle format.

Verification #

# Key-based verification
cosign verify --key cosign.pub $IMAGE

# Keyless verification
cosign verify \
  --certificate-identity=name@example.com \
  --certificate-oidc-issuer=https://accounts.example.com \
  $IMAGE

Attestations #

# Create attestation
cosign attest \
  --key cosign.key \
  --type slsaprovenance \
  --predicate predicate.json \
  $IMAGE

# Verify attestation
cosign verify-attestation \
  --key cosign.pub \
  --type slsaprovenance \
  $IMAGE

The attestation is stored as an OCI 1.1 referrer.

Discovering Referrers #

You can discover all artifacts associated with an image using the OCI referrers API:

# Using curl
curl https://registry.example.com/v2/myrepo/referrers/sha256:abc123...

# Using oras
oras discover registry.example.com/myrepo@sha256:abc123...