pkg/oci

pkg/oci/ is cosign's abstraction over OCI artifacts that carry signatures, attestations, and SBOMs. Everything that touches a registry — read, write, list, mutate, copy — goes through these interfaces.

Why this exists

google/go-containerregistry gives cosign generic OCI manifest, layer, and registry-client primitives. pkg/oci/ adds the cosign-specific layer:

• the deterministic sha256-<digest>.sig / .att / .sbom tag scheme,
• a SignedEntity interface that exposes Signatures()/Attestations() regardless of whether the underlying entity is a single image or an index,
• a Signature interface that bundles raw signature, payload, base64 form, optional cert + chain, optional Rekor bundle, and optional TSA timestamp,
• helpers for building, mutating, walking, and persisting these entities.

Layout

pkg/oci/
├── interface.go        # SignedEntity
├── signatures.go       # Signature, Signatures
├── doc.go              # package overview
├── errors.go           # sentinel errors
├── file.go             # File abstraction (raw attachment)
├── image.go            # SignedImage adapter
├── index.go            # SignedImageIndex adapter
├── mediatypes.go       # cosign-specific media types
├── empty/              # zero-signatures / zero-attestations stubs
├── internal/           # package-internal helpers (signature-storing image)
├── layout/             # OCI Image Layout (on-disk) reader/writer
├── mutate/             # append signatures, attestations, attachments
├── platform/           # platform helpers
├── remote/             # registry I/O — see remote.md
├── signature/          # tiny detached-signature wrapper
├── signed/             # SignedImage / SignedImageIndex constructors
├── static/             # build a Signature from raw bytes
└── walk/               # recursive walker for SignedEntity trees

Core interfaces

// pkg/oci/interface.go
type SignedEntity interface {
    Digest() (v1.Hash, error)
    Signatures() (Signatures, error)
    Attestations() (Signatures, error)
    Attachment(name string) (File, error)
}

// pkg/oci/signatures.go
type Signatures interface {
    v1.Image
    Get() ([]Signature, error)
}

type Signature interface {
    v1.Layer
    Annotations() (map[string]string, error)
    Payload() ([]byte, error)
    Signature() ([]byte, error)
    Base64Signature() (string, error)
    Cert() (*x509.Certificate, error)
    Chain() ([]*x509.Certificate, error)
    Bundle() (*bundle.RekorBundle, error)
    RFC3161Timestamp() (*bundle.RFC3161Timestamp, error)
}

That Signature is also a v1.Layer is what lets cosign push it through go-containerregistry without any extra plumbing — it's just another layer in an image manifest, with annotations carrying the metadata.

Sub-packages worth knowing

pkg/oci/static

Build a Signature from raw bytes:

sig, err := static.NewSignature(payload, base64.StdEncoding.EncodeToString(rawSig),
    static.WithCertChain(certPEM, chainPEM),
    static.WithBundle(rekorBundle),
)

This is the constructor the CLI uses after producing a signature in cmd/cosign/cli/sign/sign.go.

pkg/oci/mutate

Append a new signature/attestation to an existing SignedEntity:

newImg, err := mutate.AttachSignatureToEntity(entity, sig)
newImg, err := mutate.AttachAttestationToEntity(entity, dsseSig, mutate.WithReplaceOp(replace))

pkg/oci/remote

The registry I/O. Discussed separately in remote.md.

pkg/oci/layout

Read/write an OCI Image Layout on disk — backs cosign save and cosign verify --local-image.

pkg/oci/walk

Walk a SignedImageIndex and apply a function to every leaf SignedImage. Used by recursive cosign sign --recursive and cosign verify over multi-arch images.

pkg/oci/empty

Zero-value stubs. Returned when an image has no signatures/attestations attached, so callers always get a non-nil Signatures.

How the CLI uses it

graph LR
    Sign[cosign sign] -->|static.NewSignature| Sig[oci.Signature]
    Sig -->|mutate.AttachSignatureToEntity| Img[SignedEntity]
    Img -->|remote.WriteSignatures| Reg[(Registry)]
    Verify[cosign verify] -->|remote.SignedEntity| Img2[SignedEntity]
    Img2 -->|.Signatures.Get| Sigs[oci.Signature list]

Cross-references

• The deterministic-tag scheme is described in Specs / SIGNATURE_SPEC.
• Registry interactions and the --registry-* flag set: Library / OCI / remote.

Key source files

File	Purpose
pkg/oci/interface.go	SignedEntity
pkg/oci/signatures.go	Signature, Signatures
pkg/oci/signed/	Constructors: Image, ImageIndex, Entity
pkg/oci/static/	Build a Signature from raw bytes
pkg/oci/mutate/	Append signatures/attestations
pkg/oci/remote/	Registry I/O
pkg/oci/layout/	OCI Image Layout on disk
pkg/oci/walk/	Recursive SignedEntity walker