pkg/cosign

The biggest single Go package in the repo (~14,000 lines including tests). pkg/cosign/ is the verb-shaped layer that turns flag bundles (KeyOpts) into actual sign/verify side-effects.

Layout

pkg/cosign/
├── attestation/        # in-toto Statement assembly
├── bundle/             # Sigstore protobuf + legacy Rekor + TSA bundles
├── cue/, rego/         # policy language adapters
├── env/                # typed environment-variable registry
├── fulcioverifier/     # verifier-side adapter for Fulcio certs
├── git/                # github/gitlab public-key publication
├── kubernetes/         # k8s:// secret read/write
├── pivkey/, pkcs11key/ # hardware token backends (build-tag gated)
├── remote/             # registry helpers (complement to pkg/oci/remote)
├── certextensions.go   # OID constants for Fulcio cert extensions
├── common.go           # tiny shared helpers
├── ctlog.go            # CT log key wiring
├── errors.go           # exported sentinel errors
├── fetch.go            # registry → []oci.Signature
├── keys.go             # encrypted local key format
├── obsolete.go         # API-compat shim
├── rekor_factory.go    # Rekor client factory
├── tlog.go             # Rekor inclusion proof + SET check
├── tsa.go              # RFC3161 timestamp verification
├── tuf.go              # trusted_root.json loader
├── verifiers.go        # high-level "verify this image" entry points
├── verify.go           # legacy verification core (~2,000 lines)
├── verify_bundle.go    # protobuf-bundle verification path
├── verify_sct.go       # SCT verification
└── *_test.go           # heavy test coverage, including fuzz

Key abstractions

Type	File	One-liner
CheckOpts	pkg/cosign/verify.go	The grand bag of verifier inputs (CA roots, Rekor key, identities, claims, etc.). Every verify-shaped function takes one.
KeyParseError, ErrNoSignaturesFound, ErrImageTagNotFound, ErrNoMatchingSignatures, ErrMissingDiffID, …	pkg/cosign/errors.go	Sentinel errors that callers can errors.Is against to discriminate failure modes.
Signatures (re-export)	pkg/cosign/fetch.go	Walks an OCI ref and returns []oci.Signature from the deterministic .sig tag.
EncryptedKeySigner	pkg/cosign/keys.go	Local cosign-encrypted-key signer.
RekorBundle, RFC3161Timestamp, Bundle	pkg/cosign/bundle/*.go	Wire types for offline-verifiable signature metadata.

High-level entry points

A small number of functions are stable enough to call directly:

• cosign.Verify(ctx, ref, co) (pkg/cosign/verify.go) — returns the validated []oci.Signature for an OCI ref or one of the sentinel errors.
• cosign.VerifyImageAttestations(ctx, ref, co) — same, but for attestations.
• cosign.VerifyLocalImageSignatures / VerifyLocalImageAttestations (pkg/cosign/verifiers.go) — verify against an OCI Image Layout on disk (used by cosign verify --local-image and by anyone running offline).
• cosign.VerifyBundle(ctx, sig, co) (pkg/cosign/verify_bundle.go) — protobuf-bundle path; delegates to sigstore-go.
• cosign.GenerateKeyPair(pf cosign.PassFunc) (pkg/cosign/keys.go) — produce an encrypted P-256 key pair.

Verification flow inside the package

graph TD
    Caller -->|Verify ctx, ref, CheckOpts| Top[verify.go::Verify]
    Top --> Fetch[fetch.go::FetchSignaturesForReference]
    Top --> SCT[verify_sct.go::VerifySCT]
    Top --> Chain[fulcioverifier/*.go]
    Top --> TLog[tlog.go::VerifyTLogEntry]
    Top --> TSA[tsa.go::VerifyRFC3161Timestamp]
    Top --> Identity[verify.go::CheckCertificatePolicy]
    Top --> Bundle[verify_bundle.go]
    Bundle --> SgGo[sigstore-go]

For the new bundle format, the only step that runs in cosign's own code is the CheckOpts → sigstore-go translation; everything cryptographic is delegated.

Cross-references

• The flag→KeyOpts→pkg/cosign plumbing is described in How to contribute / patterns.
• Bundle wire formats: Specs.
• Anything you push or pull from a registry: Library / OCI.

Key source files

File	Purpose
pkg/cosign/verify.go	Legacy verify core (~2,000 lines)
pkg/cosign/verify_bundle.go	Protobuf-bundle verification path
pkg/cosign/verifiers.go	High-level entry points (VerifyImageSignatures, etc.)
pkg/cosign/fetch.go	Pull signatures off an OCI ref
pkg/cosign/tlog.go	Rekor inclusion proof + SET
pkg/cosign/tuf.go	Load trusted_root.json
pkg/cosign/keys.go	Encrypted local key format
pkg/cosign/errors.go	Sentinel errors