Library

Cosign's pkg/ tree is a stable Go library that other projects consume. The two best-known consumers are the in-tree cmd/conformance/ binary and sigstore/policy-controller (the Kubernetes admission-time verifier).

This section walks the library top-down — the most consumer-facing packages first, the leaf utilities last.

Package map

graph TB
    subgraph Top["Verb-shaped (high-level orchestration)"]
        Cosign[pkg/cosign]
        Policy[pkg/policy]
    end
    subgraph Mid["Building blocks"]
        OCI[pkg/oci]
        Providers[pkg/providers]
        Signature[pkg/signature]
    end
    subgraph Low["Primitives"]
        Blob[pkg/blob]
        Types[pkg/types]
    end

    Cosign --> OCI
    Cosign --> Signature
    Cosign --> Blob
    Cosign --> Types
    Policy --> OCI
    Policy --> Cosign
    Cosign --> Providers

Where to start

If you want to…	Read…
Sign or verify in your own Go code	pkg/cosign/sign.go, pkg/cosign/verify.go, pkg/cosign/verify_bundle.go
Read or write attached signatures on an OCI image	Library/OCI (pkg/oci/)
Evaluate attestations against a CUE or Rego policy	Library/Policy (pkg/policy/)
Get an OIDC token in CI without coding the provider yourself	Library/Providers (pkg/providers/)
Use the cosign-encrypted local-key format	pkg/cosign/keys.go, pkg/signature/keys.go
Pack or unpack a Sigstore protobuf bundle	pkg/cosign/bundle/

Pages

• pkg/cosign — top-level orchestration
• pkg/oci
• pkg/oci/remote
• pkg/policy
• pkg/providers

Other building blocks (single-page coverage)

pkg/signature/

Three small files (annotations.go, keys.go, keys_test.go):

• keys.go — bridge to sigstore/sigstore/pkg/signature for loading public keys from PEM/DER.
• annotations.go — stable annotation key constants (dev.sigstore.cosign/...).

pkg/blob/

Single file load.go. Reads a payload from a path, stdin, or URL, with size limits enforced via COSIGN_MAX_ATTACHMENT_SIZE. Used by every blob-shaped command (sign-blob, verify-blob, attest-blob, etc.).

pkg/types/

Three small files declaring stable string constants:

• media.go — OCI media types (SimpleSigningMediaType, DssePayloadType, etc.).
• payload.go — payload format constants.
• predicate.go — known in-toto predicate type identifiers.

Inside pkg/cosign/ — the leaves

• pkg/cosign/attestation/attestation.go — DSSE + in-toto Statement assembly.
• pkg/cosign/bundle/ — protobuf bundle (protobundle.go), legacy Rekor bundle (rekor.go), TSA bundle (tsa.go), and the v3 sign-time bundle constructor (sign.go).
• pkg/cosign/env/env.go — typed environment-variable registry.
• pkg/cosign/cue/, pkg/cosign/rego/ — policy-language adapters used by pkg/policy/.
• pkg/cosign/git/{github,gitlab} — public-key publication to GitHub/GitLab variables.
• pkg/cosign/kubernetes/secret.go — Secret (un)packing for k8s:// keys.
• pkg/cosign/pivkey/, pkg/cosign/pkcs11key/ — hardware backends (build tag gated).
• pkg/cosign/fulcioverifier/ — verification adapter for Fulcio-issued certs (CT log + chain).
• pkg/cosign/remote/ — registry-side helpers complementary to pkg/oci/remote/.
• pkg/cosign/tlog.go (~700 lines) — Rekor inclusion proof + SET (Signed Entry Timestamp) checks.
• pkg/cosign/tsa.go — RFC3161 timestamp verification.
• pkg/cosign/tuf.go — wraps theupdateframework/go-tuf/v2 to load trusted_root.json.
• pkg/cosign/verify.go (~2,000 lines) — legacy verification primitives, slowly being delegated to sigstore-go.
• pkg/cosign/verify_sct.go — SCT verification for Fulcio certs.
• pkg/cosign/keys.go — encrypted local key format.

internal/

• internal/ui/ — stderr UI (info/warn/spinner/prompt). Not part of the public API.
• internal/auth/ — internal auth helpers.
• internal/key/ — internal key helpers.
• internal/pkg/ — third-party-style internal packages.
• internal/test/ — test fixtures.

internal/ is, per Go convention, off-limits to external importers.