pkg/oci/remote

The largest sub-package under pkg/oci/. It glues pkg/oci's SignedEntity model onto a real OCI registry via go-containerregistry.

pkg/oci/remote/remote.go is the entry point (~290 lines) plus a constellation of files for tag derivation, write paths, signature reading, and option plumbing.

Tag derivation

Every cosign attached artifact lives at a deterministic tag. pkg/oci/remote/ exposes:

• SignatureTag(ref name.Reference, opts ...Option) (name.Tag, error) — sha256-<digest>.sig
• AttestationTag(ref name.Reference, opts ...Option) (name.Tag, error) — sha256-<digest>.att
• SBOMTag(ref name.Reference, opts ...Option) (name.Tag, error) — sha256-<digest>.sbom

Each follows the convention documented in specs/SIGNATURE_SPEC.md.

COSIGN_REPOSITORY and --registry-target (via RegistryClientOpt) let users push signatures into a different repo from the signed image — useful when a registry's RBAC allows pushing to a sibling repo but not to the protected production repo.

Read path

ent, err := remote.SignedEntity(ref, remote.WithRemoteOptions(opts...))
sigs, err := ent.Signatures()
list, err := sigs.Get()

SignedEntity figures out whether ref is an image or an index and returns the right adapter. Internally it calls remote.Get (go-containerregistry) and then walks to the deterministic signature tag.

Write path

err := remote.WriteSignatures(ref.Context(), entity, sig, opts...)
err := remote.WriteAttestations(ref.Context(), entity, sig, opts...)
err := remote.WriteSignedImageIndexImages(ref, entity, opts...)

Each writer:

1. Derives the destination tag.
2. Builds a v1.Image whose layer is the signature/attestation.
3. Uses remote.Write to push.

Options

pkg/oci/remote/options.go exposes a single Options struct passed via functional options. Major knobs:

• WithRemoteOptions(...remote.Option) — pass-through for go-containerregistry options (auth keychain, transport, etc.).
• WithTargetRepository(name.Repository) — override COSIGN_REPOSITORY.
• WithSignatureSuffix(string), WithAttestationSuffix(string), WithSBOMSuffix(string) — override the tag suffixes (rarely needed).

The CLI builds these from cmd/cosign/cli/options/registry.go (RegistryOptions).

Why this is the largest oci sub-package

Several concerns layered on top of each other:

• Read paths for signatures, attestations, SBOMs (with subtly different layer assembly per type).
• A "referrers" mode (post-OCI 1.1 / application/vnd.oci.image.index.v1+json referrers API) for registries that support it, plus a fallback to the legacy tag scheme. The selection is hidden behind a flag and the Repository API.
• A SignedImage / SignedImageIndex adapter that has to satisfy both pkg/oci.SignedEntity and v1.Image/v1.ImageIndex.
• Authentication knobs that piggyback on go-containerregistry's keychain.

Cross-references

• For the on-the-wire layout of these signatures, see Specs / SIGNATURE_SPEC.
• Identity matching and verification consume signatures fetched here — see Library / pkg/cosign.

Key source files

File	Purpose
pkg/oci/remote/remote.go	Top-level entry: SignedEntity, WriteSignatures, WriteAttestations
pkg/oci/remote/signatures.go	Signature-image construction
pkg/oci/remote/index.go	Index-aware reads
pkg/oci/remote/options.go	Functional options + Options struct
pkg/oci/remote/digest.go	Digest resolution helpers
pkg/oci/remote/write.go	Push side